GraphQL

User preferences and memory live in ~/Clawic/data/graphql/ (see setup.md on first use, memory-template.md for the file format). If you have data at an old location (~/graphql/ or ~/clawic/graphql/), move it to ~/Clawic/data/graphql/.

When To Use

• Writing or reviewing a schema, SDL, resolvers, mutations, or a Relay-style connection
• Diagnosing GraphQL-specific failures: N+1 query storms, non-null propagation blanking a response, partial data with errors, caches that never update
• Hardening a public or partner endpoint: depth, alias, token and complexity limits, trusted documents, introspection policy, error masking
• Evolving a live schema without breaking clients: deprecation, breaking-change checks in CI, field usage telemetry
• Splitting or composing a graph: federation subgraphs, entity keys, reference resolvers
• Not for calling somebody else's GraphQL API (their rate limits, their cursors, their auth) — that is api; not for REST resource design — that is rest-api

Quick Reference

Depth on demand: debug.md symptom→cause chains · schema.md type design · resolvers.md execution and context · n-plus-one.md batching · pagination.md connections and cursors · mutations.md writes and uploads · errors.md failure modelling · authorization.md access control · security.md DoS and disclosure · performance.md cost and latency · caching.md HTTP, CDN, APQ, entity cache · subscriptions.md realtime · federation.md multi-service graphs · client.md Apollo, Relay, urql · codegen.md typed schema and operations · testing.md tests that catch real regressions · schema-evolution.md shipping changes safely · production.md transport, timeouts, observability · rest-migration.md adoption and coexistence · commands.md toolkit.

Core Rules

1. Every field that touches a datastore goes through a per-request batch loader. Round trips without batching for a page of N parents each exposing M relation fields: 1 + N×M; with loaders: 1 + M. A page of 50 posts with author and comments is 101 queries versus 3. Build loaders in the per-request context factory — a module-level loader caches one viewer's rows and serves them to the next request (→ n-plus-one.md).
2. Nullable by default; non-null only where the value cannot fail. String! is a promise about your worst day, not your happy path. A non-null field that resolves to null nulls its nearest nullable ancestor, and [Post!]! turns one bad row into a nulled branch (→ Null Propagation).
3. Every list field is paginated and capped. Reject first > max_page_size (default 100) with a BAD_USER_INPUT error inside the resolver; clamping without saying so is only safe when clients terminate on pageInfo.hasNextPage rather than on how many items came back. An uncapped list argument is the cheapest denial of service a schema can offer.
4. Limit before you parse, then again after. Depth and complexity are validation rules that run on an already-parsed AST — a multi-megabyte document of nested braces exhausts memory in parse() before any of them execute. Ordered pipeline: body-size cap → token cap → parse → depth/alias/directive/complexity validation → execute (→ Cost Model).
5. Mutations return the modified entity, never Boolean. Payload shape: the entity (so a normalized client cache updates itself from __typename + id) plus a typed list of user errors. deleteX: Boolean forces every client into a blind refetch (→ mutations.md).
6. Mutation root fields run serially, query root fields do not. The spec guarantees document-order execution for top-level mutation selections only; sibling query fields may run in any order and concurrently. Never encode a sequence in a query, and never let a mutation's second root field depend on the first unless both are top-level siblings.
7. Recoverable failures are data; unexpected failures are the errors array. "Email already taken", "not found", "this row is not yours" → typed payload or result union, so clients handle them at compile time. Bugs, timeouts and downstream outages → throw, and let the errors array carry them (→ errors.md).
8. Mask errors in production and branch on extensions.code. The message is prose and changes without notice; the code is the contract. Stack traces, SQL fragments and the validator's "Did you mean" suggestions are schema disclosure on a public endpoint (→ security.md).
9. Deprecate on a clock set by your slowest client, remove on evidence. @deprecated(reason: "Use X") hides nothing and blocks nothing; removal is safe only after deprecation_window_days (default 90, floored by slowest_client_cycle_days) with zero operations selecting the field in usage telemetry over that same period (→ schema-evolution.md).

Null Propagation

The most misread behaviour in GraphQL. A field error nulls the field; if that field is non-null, the error climbs to the nearest nullable ancestor and nulls that instead. It never stops at a non-null boundary.

• Design consequence: non-null is for values the resolver cannot fail to produce (a NOT NULL column, a computed value). Anything crossing a network boundary is nullable.
• Null holes ([Post]) push a null check into every client loop. Prefer filtering failed elements server-side and reporting the count in extensions over shipping holes.
• Client-controlled nullability and semantic-non-null are active community proposals, not ratified spec — do not design as if the escape hatch exists (→ Where Experts Disagree).

Error Codes

extensions.code is the machine-readable contract. The codes common servers emit, and the first move for each:

• Transport status is orthogonal: a completely failed execution is still commonly HTTP 200 with an errors array. A client that only checks response.ok misses every field error.
• Define your own codes as a closed enum shared with clients. Free-form code strings end up as unparseable as messages.

Cost Model

Static cost estimate for a document, computed before execution:

cost(field) = own_cost + multiplier × Σ cost(children)
multiplier  = the field's page-size argument (first / last / limit), default 1 for non-list fields

Worked example with own_cost = 1 for every field:

query { users(first: 50) { name posts(first: 20) { title comments(first: 10) { body } } } }

comments = 1 + 10×1 = 11 · posts = 1 + 20×(1 + 11) = 241 · users = 1 + 50×(1 + 241) = 12101. Three levels with polite-looking page sizes costs twelve thousand units — which is why a depth limit alone stops nothing.

• Calibrate the budget from your own traffic: score every operation in the registry or a week of logs, take the highest legitimate score, set the ceiling above it. A round number picked by taste either rejects real clients or admits the attack.
• Aliases multiply breadth at constant depth: a: users(first:100){…} b: users(first:100){…} repeated 50 times is one shallow, cheap-looking document. Cap aliases and total tokens alongside depth.
• Cost is an estimate; latency is truth. Pair the limiter with a per-request timeout (production.md) so a cheap-scoring but slow document still dies.

Output Gates

Before emitting a schema, resolver, or client operation, verify:

• Every list field paginated and capped at max_page_size, and non-null used only where the resolver cannot fail — no [T!]! over a partially-failable source?
• Every relation field resolved through a loader constructed per request?
• Mutations named ``, taking one Input, returning the modified entity plus typed user errors?
• Authorization enforced on the loaded row inside the resolver, not by operation name at the edge?
• Cost defenses on — token cap, depth, alias cap, and either a complexity budget or a trusted-document allowlist — plus error masking with a stable extensions.code for every failure a client must handle?
• Schema change run through the breaking-change matrix (schema-evolution.md) before it merges?

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/graphql/config.yaml.

Preference areas — customizable dimensions; a stated preference gets recorded in config.yaml and applied:

• Tooling: schema registry and check tool (rover, GraphQL Hive, graphql-inspector), linter (graphql-eslint), gateway (Apollo Router, Cosmo, Mesh, none) — affects schema-evolution.md, federation.md, and the CI examples
• Conventions: mutation naming, input and payload suffixes, enum casing, edges versus a nodes shortcut, global Relay IDs versus type-scoped IDs — affects every schema snippet
• Platform: runtime and deployment target (long-lived server, serverless, edge), realtime transport (WebSocket, SSE, polling), datastore and ORM — affects subscriptions.md, production.md, and the batching examples
• Limits: the calibrated ceilings themselves once measured from the operation registry — max depth, alias cap, token cap, complexity budget, response-size ceiling, and the per-layer timeout budget (resolver < request < proxy) — recorded as each is calibrated and reused instead of a round number; affects rule 4, Cost Model, security.md, production.md, and the limit tests in testing.md
• Safety posture: how aggressively to surface hardening (masking, introspection, limits) unprompted, and whether destructive schema changes need explicit confirmation before being written
• Output format: SDL only versus SDL plus resolver code, whether generated types accompany every snippet, explanation depth
• Work order: schema reviewed and agreed before resolvers are written, or both landing together
• Cadence: release cadence per client surface (web bundle, mobile build, partner integration) behind slowest_client_cycle_days, and how often the schema check, registry or log sampling, and usage review run — affects the deprecation loop and the CI examples in schema-evolution.md
• Constraints: federation forbidden, offset pagination mandated by legacy clients, fields that must never appear in operation logs or traces

Traps

Where Experts Disagree

• Errors as data versus the errors array. Result unions give clients exhaustive typed handling of every recoverable outcome; they also multiply schema surface and force fragment spreads at every call site. Default: unions for mutations with real business outcomes, errors array for reads and for anything unexpected. The line moves with error_style.
• Introspection off in production. One camp calls it theater — the schema leaks through suggestions, error messages and your own client bundles. The other treats it as one cheap layer that raises the cost of automated scanning. Both agree it is worthless alone: disable it only together with field suggestions and a document allowlist.
• Cost analysis versus trusted documents. Allowlisting registered operations makes arbitrary-query DoS structurally impossible, and is available whenever you control every client. Cost limits are the only option for a public or partner API. Running both is normal; running neither on a public endpoint is not defensible.
• Federation versus a single schema. Federation buys team autonomy and pays in query planning, cross-subgraph batching and a composition step that can fail your deploy. The trigger is organizational — separately deployed teams owning disjoint entities — not graph size (federation.md).
• Code-first versus schema-first. Code-first keeps types and resolvers together and cannot drift; schema-first keeps the contract reviewable by people who do not read your server language, which is what makes design review real. Pick per service, record it in schema_style, never mix inside one service.

Related Skills

More Clawic skills, get them at https://clawic.com/skills/graphql (install if the user confirms):

• api — consuming somebody else's GraphQL or REST API
• rest-api — designing and building REST endpoints
• authorization — the policy models behind field-level checks
• websocket — the transport underneath subscriptions

Feedback

• If useful, star it: https://clawic.com/skills/graphql
• Latest version: https://clawic.com/skills/graphql

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/graphql.