graph_weaver 0.1.0 → 0.2.0

data/docs/scalars.md

@@ -6,9 +6,14 @@ Ruby object (and serializes back when used as a variable). A field typed
 `Money.parse(...)` inline — no runtime reflection:
 
 ```ruby
-GraphWeaver.register_scalar("Money", type: Money, requires: "bigdecimal")
+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:
 
@@ -20,7 +25,8 @@ probing the deserialize side and pairing its serializer:
 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-ins can be registered with
+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)`,
@@ -38,7 +44,7 @@ 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", type: Money, coerce: true)
+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
@@ -51,15 +57,17 @@ needs both a cast and a serialize. Off by default — the strict typed kwarg is
 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 re-registering each, flip them all on at
-once:
+`ID`/`String`→`:to_s`), so rather than opting in each, flip the default:
 
 ```ruby
-GraphWeaver.reset_scalars!(coerce: true)   # reload built-ins as coercible
-GraphWeaver.register_scalar("Money", ...)  # then add your own
+GraphWeaver.auto_coerce = true
 ```
 
-`Boolean` and `Date` have no lossless one-method conversion, so they stay strict.
+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
@@ -67,3 +75,109 @@ same path (`Date` even carries its own `require "date"`), so a later
 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.

data/docs/testing.md

@@ -1,16 +1,22 @@
 # Testing
 
+Everything here is a *client* — the one interface queries run
+through: anything with `execute(query, variables:)` returning
+`{"data" => ..., "errors" => ...}` (see [transports](transports.md)).
+Fakes, failures, and cassettes all slot in wherever a real transport
+would.
+
 `require "graph_weaver/rspec"` from your spec helper (or
-`graph_weaver/testing` outside rspec — never production code) for a
-zero-setup fake backend. `FakeExecutor` fabricates
+`graph_weaver/testing` outside rspec — never in production) for a
+zero-setup fake backend. `FakeClient` fabricates
 schema-correct responses for whatever query arrives: real enum values,
 valid `__typename` members, iso8601 date scalars — every fake casts
 cleanly through your generated structs.
 
 ```ruby
-fake = GraphWeaver::Testing::FakeExecutor.new(schema:)
+fake = GraphWeaver::Testing::FakeClient.new(schema:)
 
-person = PersonQuery.execute!(id: "1", executor: fake).person
+person = PersonQuery.execute!(fake, id: "1").person
 person.name       # => "Eliza Kertzmann" (faker-matched on field name, when faker is loaded)
 person.birthday   # => a real Date
 ```
@@ -19,20 +25,26 @@ Pin what matters, keyed by GraphQL names (schema vocabulary — keys
 survive query refactors); `"Type.field"` beats `"field"`:
 
 ```ruby
-GraphWeaver::Testing::FakeExecutor.new(schema:, overrides: {
+GraphWeaver::Testing::FakeClient.new(schema:, overrides: {
   "Person.name" => "Daniel",
   "email" => -> { "test@example.com" },
 })
 ```
 
-Or configure once, initializer-style (e.g. in `spec/support/graph_weaver.rb`):
+With rspec, one line in `spec/support/graph_weaver.rb` is the whole
+default setup — the schema auto-locates from the committed dump at
+`GraphWeaver.schema_path`, and `auto_fake` defaults on:
 
 ```ruby
-require "graph_weaver/rspec"   # rspec: seed follows --seed
+require "graph_weaver/rspec"   # seed follows --seed; every example auto-fakes
+```
 
+Configure to override any of it:
+
+```ruby
 GraphWeaver::Testing.configure do |config|
-  config.schema = MySchema
-  config.auto_fake = true              # every example runs against a fresh FakeExecutor
+  config.schema = MySchema             # an in-process class instead of the located dump
+  config.auto_fake = false             # opt out of per-example fakes
   config.mode = :faker                 # or :literal (plain typed values); nil = auto
   config.overrides = { "Person.name" => "Daniel" }
   config.list_size = 1..3
@@ -41,53 +53,51 @@ end
 ```
 
 With the rspec integration, `rspec --seed 1234` reproduces fake data
-along with test order, and `auto_fake` installs a seeded executor per
-example (generate modules *without* a baked `executor:` so they consult
-`GraphWeaver.executor`). `mode:` picks value fabrication: `:faker`
+along with test order, and `auto_fake` installs a seeded fake as the
+app client per example (generate modules *without* a baked `client:` so
+they consult `GraphWeaver.client`). `mode:` picks value fabrication: `:faker`
 (semantic, field-name matched — raises if the gem is missing),
 `:literal` (plain type-derived), or nil to auto-detect faker.
 
-**Simulating failures** — every failure mode is just an executor, so
+**Simulating failures** — every failure mode is just a client, so
 error-handling paths are testable without a server that misbehaves on cue:
 
 ```ruby
 Failure = GraphWeaver::Testing::Failure
 
-PersonQuery.execute(id: "1", executor: Failure.transport)             # TransportError (cause preserved)
-PersonQuery.execute(id: "1", executor: Failure.server(status: 502))   # ServerError
-PersonQuery.execute(id: "1", executor: Failure.throttled)             # QueryError, code THROTTLED
-PersonQuery.execute(id: "1", executor: Failure.stale_schema)          # schema_stale? => true
-PersonQuery.execute(id: "1", executor: Failure.graphql("boom", data: {...}))  # partial failure
+PersonQuery.execute(id: "1", client: Failure.transport)             # TransportError (cause preserved)
+PersonQuery.execute(id: "1", client: Failure.server(status: 502))   # ServerError
+PersonQuery.execute(id: "1", client: Failure.throttled)             # QueryError, code THROTTLED
+PersonQuery.execute(id: "1", client: Failure.stale_schema)          # schema_stale? => true
+PersonQuery.execute(id: "1", client: Failure.graphql("boom", data: {...}))  # partial failure
 
-# retries: fail twice, then succeed
-GraphWeaver::Testing::SequenceExecutor.new(Failure.transport, Failure.transport, fake)
+# retries: clients run in sequence (the last repeats) — here, two
+# transport failures and then a FakeClient serving good responses
+fake = GraphWeaver::Testing::FakeClient.new(schema:)
+GraphWeaver::Testing::Sequence.new(Failure.transport, Failure.transport, fake)
 
 # type mismatch: corrupt: derives a wrong-typed wire value for the field —
 # casting raises GraphWeaver::TypeError (overrides remain the manual escape hatch)
-GraphWeaver::Testing::FakeExecutor.new(schema:, corrupt: "Person.birthday")
+GraphWeaver::Testing::FakeClient.new(schema:, corrupt: "Person.birthday")
 
 # stale schema naming a real (sampled) field
 Failure.stale_schema(schema: MySchema)
 
 # field-level partial failure with real GraphQL null propagation: the error
 # lands with its concrete path and nulls bubble to the nearest nullable spot
-GraphWeaver::Testing::FakeExecutor.new(schema:, fail_at: { path: "person.email", code: "PRIVATE" })
+GraphWeaver::Testing::FakeClient.new(schema:, fail_at: { path: "person.email", code: "PRIVATE" })
 ```
 
-**Capture and replay** — cassettes live above the transport (no HTTP
-interception), so they work identically for HTTP, Faraday, or in-process
-executors:
+**Capture and replay** — cassettes record real API responses and replay
+them offline, above the transport (no HTTP interception):
 
 ```ruby
-# records against the live executor when the file is missing, replays after
-executor = GraphWeaver::Testing::Cassette.use("github", executor: live)
+# records against the live client when the file is missing, replays after
+cassette = GraphWeaver::Testing::Cassette.use("github", client: live)
 ```
 
-Cassettes hold real responses. Anonymize before committing — shape,
-nulls, list lengths, enums, and id relationships survive; values are
-replaced with (semantically matched) fakes:
-
-```ruby
-GraphWeaver::Testing::Cassette.new("spec/cassettes/github.yml").anonymize!(schema:)
-```
+Re-record with `GRAPHWEAVER_RECORD=1`, anonymize before committing
+(`config.anonymize = true` scrubs as recordings happen, or
+`rake graph_weaver:cassettes:anonymize` after) — the full workflow guide
+is **[cassettes](cassettes.md)**.
 

data/docs/transports.md

@@ -0,0 +1,124 @@
+# Transports
+
+A *client* is anything with `execute(query, variables:)` whose result
+`to_h`s into `{"data" => ..., "errors" => ...}` — from a full
+`GraphWeaver::Client` down to a schema class (in-process execution), a
+[FakeClient](testing.md), or anything you write. Every slot that takes a
+client accepts any of them.
+
+A *transport* is the network end of that contract — GraphQL-over-HTTP. The bundled
+two — `Transport::HTTP` (net/http, zero dependencies, loaded by default)
+and `Transport::Faraday` (opt-in) — subclass `GraphWeaver::Transport`,
+which owns the shared flow: encode the request, reclassify network
+failures as `TransportError`, raise `ServerError` on non-2xx, parse the
+body. A subclass only implements `post(body) => [status, body]` — that's
+the whole recipe for bringing your own HTTP client.
+
+## One-shot setup: a client
+
+Most apps need one line:
+
+```ruby
+github = GraphWeaver.new("https://api.example.com/graphql", auth: ENV["API_TOKEN"])
+```
+
+`GraphWeaver.new` builds a [`Client`](real_world.md): the best transport
+with auth applied (exposed as `client.transport`), the schema
+introspected lazily, and `parse`/`execute` bound to both.
+
+- `auth:` — a token; "Bearer" is assumed unless the string carries its own
+  scheme (`"Basic dXNlcjpwYXNz..."`)
+- `headers:` — anything else (API keys, custom headers)
+- `retries:` — off by default; `true` for a `Retry` with defaults,
+  or a Hash of its options
+- `cache:` / `ttl:` — schema introspection caching (see
+  [real world](real_world.md)); url clients only — a schema source never
+  introspects, so passing them raises
+- a block customizes the Faraday connection (Faraday only — raises without it)
+
+To wire generated modules that don't bake a client, make it the app's
+default: `GraphWeaver.client = github`. Anything satisfying the execute
+contract works there — testing's auto_fake swaps in a fake per example.
+
+**Transport pick**: `Transport::Faraday` when the app already loads
+faraday (its middleware/proxy/timeout ecosystem comes along), the
+zero-dependency `Transport::HTTP` otherwise. Detection is `defined?(Faraday)` —
+deliberately *not* a require: faraday rides along transitively in most
+bundles (stripe, octokit, ...), and try-requiring would silently switch
+transports on apps that never chose it. With faraday under
+`require: false`, load it before building the client.
+
+## Building blocks
+
+The client is convenience, not the only door — construct and assign
+yourself for full control:
+
+```ruby
+# zero-dependency Net::HTTP — persistent (keep-alive) connection,
+# mutex-serialized; timeouts raise retriable TransportError
+GraphWeaver::Transport::HTTP.new(
+  url,
+  headers: { ... },
+  open_timeout: 10, read_timeout: 30,  # seconds (the defaults)
+  keep_alive_timeout: 2,               # idle window before reconnecting
+)
+
+# Faraday: a url (+ optional middleware block), or a ready connection
+GraphWeaver::Transport::Faraday.new(url) do |conn|
+  conn.request :authorization, "Bearer", -> { Tokens.fetch }  # dynamic tokens
+  conn.response :logger
+end
+GraphWeaver::Transport::Faraday.new(MyApp.faraday_connection)
+
+# One Faraday::Connection is reused for the transport's lifetime, but
+# socket keep-alive depends on the ADAPTER: Faraday's default net_http
+# adapter opens a fresh connection per request. For persistent sockets
+# (and real pooling), pick a persistent adapter:
+GraphWeaver::Transport::Faraday.new(url) do |conn|
+  conn.adapter :net_http_persistent   # gem "net-http-persistent"
+end
+
+GraphWeaver.client = ...   # the app default (a Client or any of the above)
+```
+
+## Client resolution
+
+The canonical order — how a generated module finds its client (each slot
+takes a `Client` or any bare transport/fake):
+
+1. per call: `execute(some_client, ...)` — the optional first positional
+   argument, so variables keep the entire kwarg namespace
+2. per module: `MyQuery.client = something`
+3. baked constant: `Codegen.generate(..., client: MyApi::CLIENT)`
+4. the app default: `GraphWeaver.client=`
+
+Nothing set anywhere raises with a message saying which knobs exist.
+
+## Retries
+
+`Retry` wraps any client/transport:
+
+```ruby
+GraphWeaver::Retry.new(
+  inner_transport,
+  tries: 5,                        # total attempts, first included
+  backoff: :exponential,           # or :linear, or ->(attempt) { seconds }
+  base: 0.5, max: 30,              # seconds; delays clamp at max:
+  jitter: true,                    # randomize each delay by 50-100%
+  on: [GraphWeaver::TransportError, GraphWeaver::ServerError],
+  retry_if: ->(error) { ... },     # fine-grain within on:
+  retry_codes: ["THROTTLED"],      # also retry GraphQL errors by code
+)
+```
+
+Defaults: transport failures always retry (the request never arrived);
+`ServerError` only on 5xx — a 4xx is a bug in the request, retrying won't
+fix it. `retry_codes:` re-inspects response envelopes so GraphQL-level
+throttling can retry too (off by default — pass the codes your API uses).
+Exhausting `tries:` re-raises the last error (or returns the last
+code-matched response).
+
+Or via the client: `GraphWeaver.new(url, retries: { tries: 5, retry_codes: ["THROTTLED"] })`.
+
+What classifies as a transport failure is an extensible set — see
+[errors](errors.md#extending-transporterror) (`GraphWeaver.register_transport_error`).

data/graph_weaver.gemspec

@@ -3,7 +3,9 @@ require_relative "lib/graph_weaver/version"
 Gem::Specification.new do |s|
   s.authors     = ["Daniel Pepper"]
   s.description = "A typed GraphQL client for Ruby — generate Sorbet T::Structs from queries, with federation, extensibility, and testing in mind"
-  s.files       = `git ls-files * ':!:spec' ':!:sorbet' ':!:bin'`.split("\n")
+  # ".yardopts" explicitly: `git ls-files *` skips dotfiles, and
+  # rubydoc.info needs it shipped to render docstrings as markdown
+  s.files       = `git ls-files * ':!:spec' ':!:sorbet' ':!:bin' ':!:examples'`.split("\n") + [".yardopts"]
   s.homepage    = "https://github.com/dpep/graph_weaver"
   s.license     = "MIT"
   s.name        = "graph_weaver"
@@ -15,13 +17,17 @@ Gem::Specification.new do |s|
   s.add_dependency "graphql", ">= 2"
   s.add_dependency "sorbet-runtime"
 
+  s.add_development_dependency "apollo-federation" # federation integration subgraphs
   s.add_development_dependency "bigdecimal"
   s.add_development_dependency "debug"
   s.add_development_dependency "faker"
   s.add_development_dependency "faraday"
+  s.add_development_dependency "rake"
+  s.add_development_dependency "redcarpet" # yard --markup markdown
   s.add_development_dependency "rspec"
   s.add_development_dependency "simplecov"
   s.add_development_dependency "sorbet"
   s.add_development_dependency "tapioca"
   s.add_development_dependency "webrick"
+  s.add_development_dependency "yard"
 end

data/lib/graph_weaver/client.rb

@@ -0,0 +1,200 @@
+# typed: true
+# frozen_string_literal: true
+
+require_relative "codegen"
+require_relative "errors"
+require_relative "inflect"
+require_relative "retry"
+require_relative "schema_loader"
+require_relative "transport/http"
+
+# One object tying the whole flow together — transport, schema, and
+# generation:
+#
+#      github = GraphWeaver.new("https://api.github.com/graphql", auth: token, cache: true)
+#      github.register_scalar("DateTime", Time, serialize: :iso8601, requires: "time")
+#
+#      RepoQuery = github.parse("queries/repo.graphql")   # implicit schema + transport
+#      github.execute!("query { viewer { login } }")      # one-shot
+#
+# The first argument is a url (a transport is built; the schema comes
+# from introspection on first use, cached per cache:/ttl:) or a schema
+# source — a live schema class (which also executes in-process), or a
+# path/SDL/introspection dump via SchemaLoader. Pass transport: to
+# bring your own transport for a schema source.
+#
+# Clients are independent: each has its own transport, schema, and
+# scalar registrations, so one app can talk to several GraphQL servers —
+# even ones that disagree about what a "DateTime" is.
+class GraphWeaver::Client
+  URL = %r{\Ahttps?://}i
+
+  def initialize(source, auth: nil, headers: {}, retries: false, transport: nil, cache: nil, ttl: nil, &middleware)
+    if source.is_a?(String) && source.match?(URL)
+      raise ArgumentError, "pass a url or transport:, not both" if transport
+
+      @transport = wrap_retries(build_transport(source, auth:, headers:, &middleware), retries)
+    else
+      if auth || middleware || retries != false
+        raise ArgumentError, "auth:/retries:/middleware apply to a url — got a schema source"
+      end
+      if cache || ttl
+        # a schema source never introspects, so a cache would silently no-op
+        raise ArgumentError, "cache:/ttl: apply to url introspection — got a schema source"
+      end
+
+      # a live schema class doubles as an in-process transport; a loaded
+      # dump has no resolvers, so it is type information only
+      @schema = source.is_a?(Module) ? source : GraphWeaver::SchemaLoader.load(source)
+      @transport = transport || (source if source.is_a?(Module))
+    end
+
+    @cache = cache
+    @ttl = ttl
+    @scalars = {}
+    @enums = {}
+    @types = {}
+  end
+
+  # The transport queries run through: a url-built transport, an
+  # explicit transport:, or the live schema class executing in-process.
+  # Clients are self-contained — the app default never leaks in; nil for
+  # schema-dump clients (type information only).
+  attr_reader :transport
+
+  # transport, when this client must be able to execute
+  def transport!
+    transport or raise GraphWeaver::Error,
+      "this client has no transport (built from a schema dump) — pass a url or transport:"
+  end
+
+  # The schema, introspecting through the transport on first use (cached
+  # per the client's cache:/ttl:) unless one was given up front.
+  def schema
+    @schema ||= GraphWeaver::SchemaLoader.introspect(transport!, cache: @cache, ttl: @ttl)
+  end
+
+  # Client-scoped scalar registration: consulted before the global
+  # registry when this client generates code, so two clients can map the
+  # same scalar name onto different Ruby types. Same signature as
+  # GraphWeaver.register_scalar.
+  def register_scalar(graphql_name, type, cast: nil, serialize: nil, requires: nil, coerce: nil)
+    validate_registration!("scalar", graphql_name.to_s)
+    @scalars[graphql_name.to_s] =
+      GraphWeaver::Codegen::ScalarType.new(graphql_name, type, cast:, serialize:, requires:, coerce:)
+  end
+
+  # Client-scoped enum mapping: this client's generated code speaks your
+  # T::Enum for the named GraphQL enum (see Codegen::EnumType — inference
+  # by name, map: for renames, fallback: to absorb unknown wire values).
+  def register_enum(graphql_name, type, map: nil, fallback: nil, requires: nil)
+    validate_registration!("enum", graphql_name.to_s)
+    @enums[graphql_name.to_s] =
+      GraphWeaver::Codegen::EnumType.new(graphql_name, type, map:, fallback:, requires:)
+  end
+
+  # Bulk, inference-only form: register_enums("Species" => PetKind, ...)
+  def register_enums(mappings)
+    mappings.each { |graphql_name, type| register_enum(graphql_name, type) }
+  end
+
+  # Client-scoped type helpers: include app-owned modules into every
+  # struct this client generates from the named GraphQL type — pass
+  # modules, or a block to build one inline. Additive with global
+  # registrations (see GraphWeaver.register_type).
+  def register_type(graphql_name, *mixins, requires: nil, &block)
+    validate_registration!("type", graphql_name.to_s)
+    entry = @types[graphql_name.to_s] ||= { mixins: [], requires: [] }
+    GraphWeaver::Codegen.add_type_helpers(entry, graphql_name, mixins, requires, block)
+  end
+
+  # Parse a query (a .graphql path or raw string) into a typed module
+  # bound to this client's schema, scalars, enums, helpers, and transport
+  # (including a live schema class executing in-process — the module came
+  # from this client, so it runs against it; pass a client per call to
+  # override, e.g. with a fake).
+  def parse(query, name: nil)
+    GraphWeaver.parse(schema:, query:, name:, client: transport,
+      scalars: @scalars, enums: @enums, types: @types)
+  end
+
+  # Parse every .graphql query in a directory into typed modules, named
+  # like generation would name them — the no-build-step analog of
+  # generate! + load_generated!:
+  #
+  #      github.load_queries!                        # queries/person.graphql => ::PersonQuery
+  #      github.load_queries!(namespace: Github)     # => Github::PersonQuery
+  #
+  # Reloadable (constants are replaced), so it suits consoles and dev.
+  # Returns the modules.
+  def load_queries!(dir = GraphWeaver.queries_path, namespace: Object)
+    Dir[File.join(dir, "*.graphql")].sort.map do |path|
+      name = "#{GraphWeaver::Inflect.camelize(File.basename(path, ".graphql"))}Query"
+      namespace.send(:remove_const, name) if namespace.const_defined?(name, false)
+      GraphWeaver.log(:info) { "loaded #{name} from #{path}" }
+      namespace.const_set(name, parse(path))
+    end
+  end
+
+  # One-shot dynamic execution — parse + execute, returning the typed
+  # Response envelope (execute! returns the result or raises). Variables
+  # are plain kwargs, exactly as on a generated module; graphql-cased
+  # string keys work too.
+  def execute(query, **variables)
+    mod = parse(query)
+    kwargs = variables.to_h { |key, value| [GraphWeaver::Inflect.underscore(key.to_s).to_sym, value] }
+    mod.execute(transport!, **kwargs)
+  end
+
+  def execute!(query, **variables)
+    execute(query, **variables).data!
+  end
+
+  private
+
+  # Fail a typo'd registration at the call site when the schema is
+  # already in hand (a schema-source client, or a url client after first
+  # use) — immediate feedback in consoles. Lazily-introspecting clients
+  # get the same check at generation time instead; never trigger an
+  # introspection just to validate a name.
+  def validate_registration!(kind, name)
+    return unless @schema
+
+    GraphWeaver::Codegen.validate_registration!(@schema, kind, name)
+  end
+
+  # auth: is a token — "Bearer" is assumed unless the string carries its
+  # own scheme ("Basic dXNlcjpwYXNz..."). Transport pick: Faraday when
+  # the app already loads it (its middleware/proxy/timeout ecosystem
+  # comes along), the zero-dependency Transport::HTTP otherwise.
+  # Detection is `defined?(Faraday)` — deliberately NOT a require:
+  # faraday rides along transitively in most bundles (stripe, octokit,
+  # ...), and try-requiring would switch transports on apps that never
+  # chose it. With faraday under `require: false`, load it before
+  # building the client.
+  def build_transport(url, auth:, headers:, &middleware)
+    headers = headers.dup
+    if auth
+      headers["Authorization"] ||= auth.include?(" ") ? auth : "Bearer #{auth}"
+    end
+
+    if defined?(::Faraday)
+      require_relative "transport/faraday"
+      GraphWeaver::Transport::Faraday.new(url, headers:, &middleware)
+    elsif middleware
+      raise ArgumentError, "middleware blocks require the faraday gem"
+    else
+      GraphWeaver::Transport::HTTP.new(url, headers:)
+    end
+  end
+
+  # retries: is off by default — true for Retry defaults, or a
+  # Hash of its options
+  def wrap_retries(transport, retries)
+    case retries
+    when true then GraphWeaver::Retry.new(transport)
+    when false, nil then transport
+    else GraphWeaver::Retry.new(transport, **retries)
+    end
+  end
+end