graph_weaver 0.0.1 → 0.2.0

data/docs/generated_modules.md

@@ -0,0 +1,229 @@
+# Generated modules
+
+`GraphWeaver::Codegen` turns one GraphQL operation into one `# typed: strict`
+Ruby module. Everything `srb tc` knows about your query results comes from this
+file — there is no runtime schema, no lazy wrapper, no reflection.
+
+This is the production path — checked in, reviewed, statically checked
+(assembled step by step in the [getting started](getting_started.md), including
+[what Sorbet does and doesn't require](getting_started.md#sorbet-with-or-without)).
+For consoles and dev there's [dynamic mode](#dynamic-mode); for one-off
+scripts, `client.execute!` skips modules entirely.
+
+## Generating
+
+The workflow that keeps generated code honest: queries live as `.graphql`
+files (the source of truth), generation writes the Ruby, and verification
+fails when the two drift. The conventional layout (configurable via
+`GraphWeaver.queries_path` / `generated_path` / `schema_path`):
+
+```text
+app/graphql/
+  schema.json        # introspection dump (or schema.graphql SDL)
+  queries/           # *.graphql — hand-written, reviewed
+  generated/         # *_query.rb — generated, checked in, never edited
+```
+
+The schema dump is step 0 — codegen reads it, never a live endpoint.
+`cache: true` on a url client writes it on first introspection
+(`GraphWeaver.new(url, cache: true).schema` in a console bootstraps it);
+generating without one fails pointing at exactly that.
+
+Rake tasks (self-registering in Rails; elsewhere add
+`require "graph_weaver/tasks"` to your Rakefile):
+
+```sh
+rake graph_weaver:generate    # queries_path -> generated_path
+rake graph_weaver:verify      # fail if anything is stale — run in CI
+```
+
+Scalar/enum/type registrations are baked into generated source, so they
+must run before the tasks do. In Rails they will — the tasks depend on
+`:environment`, which runs your initializers. Outside Rails, require the
+file that does your registrations from the Rakefile yourself.
+
+Or call the same APIs directly:
+
+```ruby
+schema = GraphWeaver::SchemaLoader.load(GraphWeaver.schema_path)
+GraphWeaver.generate!(schema:)            # write the modules
+GraphWeaver.verify_generated!(schema:)    # the freshness guard, one line in a spec
+```
+
+In Rails, loading is automatic — the Railtie requires every file under
+`generated_path` at boot, after your initializers (so registrations run
+first). Elsewhere it's explicit, factory_bot-style:
+
+```ruby
+GraphWeaver.load_generated!   # require every file under generated_path
+```
+
+(Plain requires, not Zeitwerk: Zeitwerk would expect
+`Generated::PersonQuery` from `generated/person_query.rb`, and generated
+code only changes on regeneration — restart, like a schema migration.)
+
+Regenerate when: a query changes, the schema changes (a
+[`schema_stale?`](errors.md) error in production is the late signal — refresh
+the schema dump and regenerate), a scalar registration changes, or GraphWeaver
+itself upgrades (emission may differ across versions; `verify_generated!`
+catches it).
+
+Introspected dumps record their source url, so drift is checkable ahead
+of the late signal: `rake graph_weaver:schema:verify` re-introspects the
+recorded url and fails when the server has moved;
+`rake graph_weaver:schema:refresh` rewrites the dump
+(`GRAPHWEAVER_AUTH` supplies a token for private APIs). Don't confuse
+the two verifies: `graph_weaver:verify` asks "is the generated code
+fresh?" — local, every CI run; `graph_weaver:schema:verify` asks "has the
+*server* drifted from the dump?" — network, needs the recorded url, run
+on a schedule.
+
+In development, skip the build entirely — `client.load_queries!` parses
+every query file into modules with the same names generation would use
+(see [dynamic mode](#dynamic-mode)).
+
+## Anatomy
+
+```ruby
+module PersonQuery
+  QUERY = "..."                  # the operation, verbatim
+
+  class Result < T::Struct       # the response shape, exactly as selected
+    class Person < T::Struct
+      const :name, String        # non-null in the schema
+      const :birthday, T.nilable(Date)
+
+      def self.from_h(data) ...  # generated casting — no reflection
+    end
+
+    const :person, T.nilable(Person)
+  end
+
+  def self.client ...            # default client (see below)
+  def self.execute(client = nil, id:)   # -> GraphWeaver::Response[Result]
+  def self.execute!(client = nil, id:)  # -> Result, or raises QueryError
+end
+```
+
+- `execute` returns the **envelope** — `GraphWeaver::Response[Result]` with
+  `#data`, `#data!`, `#errors`, `#extensions` — so partial data and
+  cost/throttle metadata survive.
+- `execute!` is the shortcut: the typed result or a raised
+  `GraphWeaver::QueryError`.
+
+## Variables become typed kwargs
+
+```graphql
+mutation($name: String!, $species: Species!, $note: String) { ... }
+```
+
+```ruby
+AddPetQuery.execute!(name: "Rex", species: AddPetQuery::Species::Dog)
+```
+
+- required vs optional falls out of nullability and defaults: nullable or
+  defaulted variables become optional kwargs (nil is omitted from the wire,
+  so server-side defaults apply)
+- enum variables generate module-level `T::Enum`s and accept the enum or
+  its wire value (`species: Species::Dog` or `species: "DOG"`)
+- custom scalars serialize through the [scalar registry](scalars.md)
+
+**Input objects**: when an operation's only variable is a required input
+object (the Relay convention), the input's fields flatten straight into
+`execute`'s kwargs — no wrapper at the call site:
+
+```graphql
+mutation($input: AdoptionInput!) { adopt(input: $input) { ... } }
+```
+
+```ruby
+AdoptQuery.execute!(name: "Rex", species: "DOG", nickname: "Rexy")
+```
+
+The wrapping level is rebuilt on the wire, and each field type-checks
+exactly like a variable would. Operations with more than one variable (or
+a nullable input) keep the variable-per-kwarg surface — there the input
+kwarg accepts the generated `T::Struct` or a plain hash (`.coerce`
+normalizes underscored Symbol/String keys; enums accept wire values;
+nested inputs accept hashes; unknown keys raise with a spellchecked
+hint rather than silently dropping):
+
+```ruby
+AdoptQuery.execute!(input: { name: "Rex", species: "DOG" }, detail: true)
+```
+
+The structs themselves are module-level (`AdoptQuery::AdoptionInput`) with
+`serialize` (aliased as `to_h`) producing the wire hash — optional fields
+default nil and stay off the wire. Nested inputs work (dependencies emit
+first), including recursive ones — Hasura's self-referential `bool_exp`
+filters generate cleanly (`_and:`/`_not:` fields typed as the struct
+itself), so variable-driven filtering works:
+
+```ruby
+where = mod::PokemonBoolExp.coerce(
+  _and: [{ name: { _like: "%chu" } }, { _not: { name: { _eq: "raichu" } } }],
+)
+mod.execute!(where:)
+```
+
+## Selections
+
+- **Fragments** — inline fragments and named spreads flatten into the
+  selection; type conditions match exact names or interfaces/unions the type
+  belongs to.
+- **Unions and interfaces** — when the selection *varies by concrete
+  type*, each abstract site emits a module: one member struct per
+  possible type, `Type = T.type_alias { T.any(...) }`, and a `from_h`
+  dispatching on `__typename` — which generation therefore *requires* in
+  the selection (the wire response carries no type tag unless you ask).
+  Two narrower shapes skip the dispatch (and the `__typename`) entirely:
+  interface-level fields only → one shared struct; a single `... on X`
+  condition and nothing else → `X`'s struct, always nilable — a
+  non-matching runtime type comes back as `nil`, so narrowing doubles as
+  filtering.
+- **`@skip` / `@include`** — a directive-conditional field may be absent from
+  the response regardless of schema nullability, so its generated type is
+  always nilable.
+- **Aliases** — result keys follow aliases; props are the underscored alias.
+
+Props are always snake_case (`nameWithOwner` → `name_with_owner`). Reaching
+for the wire name is a classic stumble, so it fails helpfully at both
+layers: `srb tc` flags it statically, and at runtime (consoles, dynamic
+mode) the struct raises a NoMethodError naming the prop that does exist —
+`use 'name_with_owner'` for the exact wire name, `did you mean ...?` for
+a near-miss typo in either casing.
+
+## Naming
+
+Module names derive from the operation name (`query GetPerson` → `GetPerson`);
+`GraphWeaver.parse` on a `.graphql` file derives from the file name
+(`person.graphql` → `PersonQuery`). Pass `module_name:`/`name:` to override.
+`Codegen.generate` requires a deliberate name for anonymous operations; dynamic
+`parse` defaults to `Query` (its constants are container-scoped, so collisions
+are impossible).
+
+Nested struct names come from GraphQL type names, disambiguated one level by
+field name on collision.
+
+## Clients
+
+A client is anything with `execute(query, variables:)` whose result `to_h`s
+into `{"data" => ..., "errors" => ...}`. Resolution: per call → per module →
+baked constant → `GraphWeaver.client` — the
+canonical list lives in [transports](transports.md#client-resolution).
+
+Generate *without* a baked constant when you want modules to follow the
+app default (`GraphWeaver.client =` in an initializer) — that's also what
+lets [testing's auto_fake](testing.md) swap in a fake per example.
+
+## Dynamic mode
+
+`GraphWeaver.parse` generates + evals in one step (no build artifact, evaled
+into an anonymous container — no global constants leak). Same runtime
+semantics; invisible to `srb tc`, so prefer the build step where static
+checking matters. `GraphWeaver.execute(schema:, query:, variables: {})` is
+the one-shot form.
+
+Generated source is eval'd, so inputs are validated: module names must be
+constant names, and query heredocs can't be terminated early. Still: queries
+are code — don't feed untrusted strings to parse.

data/docs/getting_started.md

@@ -0,0 +1,134 @@
+# Getting started: the production path (Rails)
+
+The setup that ships: queries live as `.graphql` files, generation writes
+`# typed: strict` Ruby you check in, and CI fails when anything drifts.
+Mostly copy/paste. (Exploring an API from a console instead? Start with
+[dynamic mode](real_world.md) — no build step.)
+
+Rails is assumed below; the [non-Rails note](#not-rails) at the bottom
+covers the one difference.
+
+## 1. Install
+
+```ruby
+# Gemfile
+gem "graph_weaver"
+```
+
+## 2. Bootstrap the schema dump
+
+Codegen reads a schema dump at `app/graphql/schema.json`
+(`GraphWeaver.schema_path`). You never write this file by hand —
+`cache: true` writes it on first introspection. Bootstrap once from a
+console:
+
+```ruby
+GraphWeaver.new("https://api.example.com/graphql", auth: ENV["API_TOKEN"], cache: true).schema
+```
+
+Skip this step and the generate task tells you exactly that — the error
+message is the documentation. Prefer PR-reviewable diffs? `cache: :graphql`
+writes SDL instead of introspection JSON; both generate identical code.
+
+Note `cache:`/`ttl:` apply only to url clients — a schema source (a live
+class or a dump) never introspects, so passing them raises.
+
+## 3. Wire the client
+
+```ruby
+# config/initializers/graph_weaver.rb
+GraphWeaver.client = GraphWeaver.new(
+  "https://api.example.com/graphql",
+  auth: ENV["API_TOKEN"],
+  cache: true,   # reuses the committed dump; delete the file to re-introspect
+)
+
+# custom scalars/enums/type helpers — register globally, so the rake
+# tasks bake them into generated source
+GraphWeaver.register_scalar("DateTime", Time, serialize: :iso8601, requires: "time")
+```
+
+`GraphWeaver.client =` is the load-bearing line: generated modules
+without a baked transport resolve to it at execute time (the full
+[resolution order](transports.md#client-resolution)). The generated
+modules themselves load at boot automatically (the Railtie requires
+everything under `generated_path`, after your initializers run) —
+outside Rails, call `GraphWeaver.load_generated!` wherever your app
+boots.
+
+## 4. Rake tasks — nothing to do
+
+In Rails the `graph_weaver:*` tasks register themselves (a Railtie), and
+they depend on `:environment`, so your initializer — and its
+registrations, which are baked into generated source — runs first.
+Outside Rails, add `require "graph_weaver/tasks"` to your Rakefile.
+
+## 5. Write a query, generate, commit
+
+```graphql
+# app/graphql/queries/person.graphql
+query($id: ID!) {
+  person(id: $id) {
+    name
+    birthday
+  }
+}
+```
+
+```sh
+rake graph_weaver:generate   # writes app/graphql/generated/person_query.rb
+```
+
+Commit the schema dump and the generated files. Generated code is
+reviewed like any other code — and never edited by hand.
+
+```ruby
+PersonQuery.execute!(id: "1").person&.name   # typed, via GraphWeaver.client
+```
+
+## 6. Test against fakes
+
+```ruby
+# spec/support/graph_weaver.rb
+require "graph_weaver/rspec"
+```
+
+That's the whole setup: the schema auto-locates from the committed dump
+and `auto_fake` defaults on, so every query in every example executes
+against a seeded, schema-correct `FakeClient` — no server, no stubs,
+and `rspec --seed 1234` reproduces the fake data along with test order.
+Pin values with `overrides:`, simulate failures with `Failure.*`, opt
+out with `config.auto_fake = false` — see [testing](testing.md).
+
+## 7. Verify in CI
+
+```sh
+rake graph_weaver:verify          # generated code fresh? fails on any drift
+rake graph_weaver:schema:verify   # server drifted? re-introspects and compares
+```
+
+Two different questions. `graph_weaver:verify` checks that the committed
+generated files match what the current schema + queries + registrations
+would produce — run it in every CI build. `graph_weaver:schema:verify`
+asks whether the *server* has moved since the dump was taken — it needs
+network, a dump with a recorded source url (introspected dumps have one),
+and `GRAPHWEAVER_AUTH` for private APIs; run it on a schedule and refresh
+with `rake graph_weaver:schema:refresh`.
+
+## Sorbet, with or without
+
+`sorbet-runtime` is a hard dependency, so generated `T::Struct`s and sigs
+enforce at runtime in every app — no Sorbet setup required on your end.
+The *static* layer (`srb tc` flagging a typo'd field before anything
+runs) applies only when your app runs Sorbet, and only to checked-in
+generated files — dynamic `parse` is invisible to `srb tc`. Everything
+works without Sorbet; codegen plus Sorbet is what moves type errors from
+runtime to CI.
+
+## Not Rails?
+
+Everything above works the same, minus the Railtie conveniences: add
+`require "graph_weaver/tasks"` to your Rakefile yourself, and — since
+there's no `:environment` hook to run your registrations — require the
+file that does them from the Rakefile too. `GraphWeaver.load_generated!`
+goes wherever your app boots instead of an initializer.

data/docs/logging.md

@@ -0,0 +1,33 @@
+# Logging
+
+Silent by default. Point `GraphWeaver.logger` at anything
+stdlib-Logger-compatible and the whole flow narrates itself — in Rails
+the railtie wires `Rails.logger` automatically (set
+`GraphWeaver.logger = nil` in an initializer to opt out):
+
+```ruby
+GraphWeaver.logger = Logger.new($stdout, level: Logger::INFO)
+```
+
+What logs at which level — pick the level, get the story:
+
+| Level | What you see |
+|-------|--------------|
+| `debug` | the wire: query + variables per call (long queries truncated), response status/bytes, request timing, connection open/drop, dynamically parsed modules |
+| `info` | schema introspection (with timing) and cache hits/misses, generated files written, query modules loaded |
+| `warn` | every GraphWeaver error raised — `TransportError`, `ServerError`, `QueryError`, `ValidationError`, `TypeError` |
+
+Every line carries `graph_weaver` as the progname, so formatter-based
+filtering works out of the box. Wire lines are tagged
+`[req 3 FilteredPokemon]` — a per-process request id plus the operation
+name — so a request's lines stay paired when threads interleave.
+
+Debugging a misbehaving integration is the intended use: crank to
+`Logger::DEBUG` and you'll see exactly what went on the wire, what came
+back, whether the schema came from cache or a live introspection, and
+which connection served it.
+
+**PII note**: queries, variables, and response sizes appear at debug
+only — variables can carry user data, so keep production loggers at
+info or above (or scrub in your formatter). Auth headers never log at
+any level.

data/docs/real_world.md

@@ -0,0 +1,53 @@
+# Against a real API
+
+The exploratory tour: point a client at a live endpoint and go, no build
+step — ideal for consoles, spikes, and getting a feel for an API. What
+ships is the checked-in codegen path in the [getting started](getting_started.md);
+this page is how you get there (the `parse` below becomes a `.graphql`
+file plus `rake graph_weaver:generate`, everything else stays).
+
+Everything hangs off a client — transport, schema, and scalars for one
+server. GitHub's API, end to end:
+
+```ruby
+require "graph_weaver"
+
+# transport + auth in one object (see docs/transports.md for retries and
+# advanced setup). cache: true dumps the schema at GraphWeaver.schema_path
+# on first introspection — the same file rake graph_weaver:generate reads —
+# and any fresh dump already present is reused regardless of format. The
+# extension picks the format: .json verbatim, .graphql SDL (reviewable
+# diffs) — or say cache: :graphql. Introspected dumps record their source
+# url in a header, so a stale dump says where it came from.
+github = GraphWeaver.new("https://api.github.com/graphql", auth: `gh auth token`.strip, cache: true)
+
+# map GitHub's DateTime scalar onto Time (cast inferred from Time.parse) —
+# scoped to this client; GraphWeaver.register_scalar sets the global default
+github.register_scalar("DateTime", Time, serialize: :iso8601, requires: "time")
+
+RepoQuery = github.parse(<<~GRAPHQL)
+  query($owner: String!, $name: String!) {
+    repository(owner: $owner, name: $name) {
+      nameWithOwner
+      createdAt
+      stargazerCount
+    }
+  }
+GRAPHQL
+
+repo = RepoQuery.execute!(owner: "dpep", name: "graph_weaver").repository
+repo&.name_with_owner   # => "dpep/graph_weaver"
+repo&.created_at        # => 2026-07-07 ... (a real Time)
+repo&.stargazer_count   # => Integer
+```
+
+Clients are independent — build one per server, each with its own
+transport, schema, and scalar mappings. The introspection step (seconds
+on a big API) happens lazily on first `schema`/`parse` and caches per
+`cache:`/`ttl:`; for finer control the pieces are all public
+(`GraphWeaver::SchemaLoader.introspect(transport, cache:, ttl:)`, or cache
+`introspect(transport).to_json` in Rails.cache and `SchemaLoader.load` it).
+
+The same flow runs as one-off integration specs against the live GitHub
+and Countries APIs — `make integration` (network; GitHub auth via
+`gh auth token` or `GITHUB_TOKEN`).

data/docs/scalars.md

@@ -0,0 +1,183 @@
+# Custom scalars
+
+Teach the generator how a GraphQL custom scalar deserializes into a rich
+Ruby object (and serializes back when used as a variable). A field typed
+`Money` then generates `const :price, T.nilable(Money)` and casts with
+`Money.parse(...)` inline — no runtime reflection:
+
+```ruby
+GraphWeaver.register_scalar("Money", Money, requires: "bigdecimal")
+```
+
+Registrations are global by default. A [client](transports.md) scopes
+them: `client.register_scalar(...)` overlays the global registry for that
+client's generation only — so two servers can disagree about what a
+`DateTime` is, and neither leaks into the other.
+
+Pass a real class as `type:` and the cast/serialize are **inferred** from it by
+probing the deserialize side and pairing its serializer:
+
+| the class defines | cast          | serialize      |
+|-------------------|---------------|----------------|
+| `.parse`          | `Type.parse(v)` | `v.to_s`     |
+| `.load`           | `Type.load(v)`  | `Type.dump(v)` |
+
+so the common case needs nothing more. Probing the *deserialize* side is
+deliberate — every object has `#to_s`, so inferring off it would wrongly wrap
+plain types like `String`/`Integer`; requiring a `.parse`/`.load` the type
+actually defines avoids that (and is why the built-in scalars — `Date`, `ID`,
+`Int`, and friends, pre-registered and detailed below — can be registered with
+their real class constants). Override explicitly when you need to:
+
+- a `Symbol` method name, nothing to misspell: `cast: :load` → `Money.load(expr)`,
+  `serialize: :to_json` → `expr.to_json`
+- a `Proc` for anything a method name can't express: `cast: ->(expr) { "Money.new(#{expr})" }`
+- `:itself` to force pass-through, opting out of inference (rare)
+
+`type:` also accepts a plain string (`"BigDecimal"`) when you'd rather not
+reference the class. `requires:` (a string or array) names files emitted as
+`require`s atop the generated source so the cast/type resolve. When `type:` is
+a real class (so the runtime is loaded), each path is also `require`d at
+registration — a typo fails now, not in the generated file.
+
+Pass `coerce: true` to let a variable of this scalar accept **either** the value
+object **or** its raw input, normalizing the latter through the cast:
+
+```ruby
+GraphWeaver.register_scalar("Money", Money, coerce: true)
+# generated execute now takes T.any(Money, String); "12.00" is parsed
+StoreQuery.execute(budget: "12.00")          # Money.parse("12.00") under the hood
+StoreQuery.execute(budget: Money.new(1200))  # passed straight through
+```
+
+Bad input still explodes (the cast raises), so some safety survives; coercion
+needs both a cast and a serialize. Off by default — the strict typed kwarg is the norm.
+
+`coerce:` also takes a **Symbol** naming a conversion method, for built-ins where
+a plain method is the whole story — `coerce: :to_f` makes a variable accept
+`5`/`"5"` and `.to_f` it, sending a native number (not `"5.0"`) on the wire. The
+convertible built-ins already know theirs (`Float`→`:to_f`, `Int`→`:to_i`,
+`ID`/`String`→`:to_s`), so rather than opting in each, flip the default:
+
+```ruby
+GraphWeaver.auto_coerce = true
+```
+
+Resolved lazily at generation time (set it any time before you generate),
+it gives convertible built-ins their conversion and any scalar with a full
+cast/serialize pair (`Date`, your `Money`) parse-style coercion; an explicit
+`coerce:` on a registration always wins. `Boolean` has no lossless
+one-method conversion, so it stays strict.
+
+The built-in scalars (`Date`, `ID`, `Int`, …) are pre-registered through the
+same path (`Date` even carries its own `require "date"`), so a later
+`register_scalar` overrides them; `GraphWeaver.reset_scalars!` restores the
+defaults (`reset_scalars!(coerce: true)` restores them coercible) and
+`clear_scalars!` empties the registry. Register before generating — it's a
+codegen-time concern, baked into the emitted source.
+
+## Enums: map onto your own T::Enum
+
+By default each generated module grows its own `T::Enum` per GraphQL
+enum — `AddPetQuery::Species`, `SearchQuery::Result::...::Species`, one
+per module that touches it. That's fine until your app has its own
+domain enum, and then the boundary shuffle starts:
+
+```ruby
+# your domain already speaks PetKind — it's in your models, your
+# ActiveRecord enum column, your case statements
+class PetKind < T::Enum
+  enums { Cat = new("cat"); Dog = new("dog") }
+end
+
+# without a mapping, every call site converts by hand, in both directions
+kind = PetKind.deserialize(pet.species.serialize.downcase)      # response -> domain
+AddPetQuery.execute!(species: kind.serialize.upcase)            # domain -> wire
+```
+
+Two enums for one concept, glue at every crossing, and each generated
+module has its *own* incompatible `Species`, so a pet from `SearchQuery`
+and a pet from `AddPetQuery` don't even compare. Register the mapping
+once and the seam disappears — generated code speaks your enum
+everywhere, casting wire values in and serializing members out:
+
+```ruby
+GraphWeaver.register_enum("Species", PetKind)                # global
+api.register_enums("Species" => PetKind, "Role" => Role)     # or per client, in bulk
+
+pet.species                                   # => PetKind::Dog — compare, case, persist directly
+pet.species == other_pet.species              # same type across every query
+AddPetQuery.execute!(species: PetKind::Cat)   # or "CAT" — members and wire values both work
+```
+
+**When to reach for it**: the enum has a life outside the API — it's
+persisted, matched in business logic, or shared across queries. **When
+not to bother**: display-only values you read and forget; the per-module
+generated enums are self-contained and need zero setup.
+
+The mapping is inferred by name (`"CAT"` ↔ `PetKind::Cat`,
+case/underscore-insensitive against each member's serialized value), so
+aligned enums need only the one line. When names diverge, `map:` pins the
+exceptions and merges over inference:
+
+```ruby
+GraphWeaver.register_enum("Species", PetKind, map: { "FELINE" => PetKind::Cat })
+```
+
+Two safety properties do the real work:
+
+- **Exhaustiveness at generation**: every value the schema declares must
+  resolve to a member, or generation fails naming the gaps
+  (`PetKind has no member for Species value(s) DOG — add them, pin with
+  map:, or absorb with fallback:`). Your enum drifting from the server's
+  is caught at `rake graph_weaver:generate`, not in production.
+- **`fallback:` for forward-compat**: `fallback: PetKind::Unknown` makes
+  *casting* absorb wire values the server added after you generated —
+  responses keep flowing instead of raising. Inputs stay strict either
+  way: a typo'd input is your bug, not drift.
+
+The translation tables are emitted into the generated source
+(`SPECIES_FROM_WIRE` / `SPECIES_TO_WIRE`) — reviewable in the diff, no
+runtime registry. And because registration can be client-scoped, two
+servers with different ideas of `"Species"` can map onto different (or
+the same) domain enums without touching each other.
+
+## Type helpers: your logic on generated structs
+
+Derived values (display names, emoji, predicates) belong next to the
+data but not *in* it — rewriting wire values on the way in destroys the
+raw truth. Register a plain module and every struct generated from that
+GraphQL type includes it, whatever query it appears in:
+
+```ruby
+module PetHelpers
+  def adult? = birthday && birthday < Date.today << 24
+  def display_name = adult? ? "#{name} 🦴" : "#{name} 🐶"
+end
+
+GraphWeaver.register_type("Pet", PetHelpers)   # or api.register_type(...)
+
+pet.display_name   # => "Shelby 🦴"
+pet.name           # => "Shelby" — the wire value stays honest
+```
+
+Because the include is emitted into the generated source, `srb tc` checks
+the helpers against each query's actual selection — a helper that calls
+`birthday` on a query that never selected it is a **static error**, which
+doubles as selection-completeness checking. Registrations are additive
+(global plus client-scoped stack), and fakes/cassettes get the behavior
+automatically since it lives on the struct.
+
+For quick decoration, build the mixin inline — the block is
+`module_eval`'d into a fresh module auto-named under
+`GraphWeaver::TypeHelpers` so generated files can reference it:
+
+```ruby
+api.register_type("Pet") do
+  def display_name = "#{name} 🐶"
+end
+```
+
+Same runtime behavior, one caveat: `srb tc` can't see into block-defined
+methods, so prefer a named module where static checking matters —
+complexity on demand.