graph_weaver 0.1.0 → 0.2.1

data/docs/cassettes.md

@@ -0,0 +1,76 @@
+# Cassettes: capture and replay
+
+Cassettes record real API responses and replay them in tests — above the
+transport (a client wrapping a client), so there's no HTTP
+interception and they work identically over HTTP, Faraday, or in-process
+execution. A cassette is a YAML file of `{query, variables, response}`
+entries, matched on the normalized query + variables.
+
+## The workflow
+
+```ruby
+# spec: replay when the cassette exists, record against `live` when not
+cassette = GraphWeaver::Testing::Cassette.use("github", client: live)
+result = RepoQuery.execute!(cassette, owner: "dpep", name: "graph_weaver")
+```
+
+1. **Record** — first run hits the live API and writes
+   `spec/cassettes/github.yml` (`Testing.config.cassette_dir` resolves bare
+   names).
+2. **Anonymize** — cassettes hold real data; scrub before committing (below).
+3. **Commit** — tests now run offline, fast, deterministic.
+4. **Re-record** when the API's real behavior changes:
+
+   ```sh
+   GRAPHWEAVER_RECORD=1 bundle exec rspec   # every Cassette.use records afresh
+   ```
+
+   (`Testing.config.record = true` is the programmatic equivalent.)
+
+Replaying an unrecorded request raises `MissingRecording` with the query
+and the path — no silent fabrication.
+
+## Anonymization
+
+Anonymizing rewrites recorded values through the same engine
+[FakeClient](testing.md) uses, while preserving everything that makes
+the recording faithful:
+
+| preserved | replaced |
+|-----------|----------|
+| shape: keys, list lengths, null positions | strings (semantically: emails look like emails) |
+| enums, booleans, `__typename` | numbers, dates |
+| id *relationships* (same original id → same fake id) | the id values themselves |
+
+Three ways to run it:
+
+```ruby
+# 1. as recordings happen — assertions you write against the recording
+#    run hold on replay, and real data never touches disk
+GraphWeaver::Testing.configure do |config|
+  config.schema = MySchema
+  config.anonymize = true
+end
+
+# 2. after the fact, per cassette
+GraphWeaver::Testing::Cassette.new("spec/cassettes/github.yml").anonymize!(schema:)
+```
+
+```sh
+# 3. the whole cassette_dir at once
+rake graph_weaver:cassettes:anonymize
+```
+
+Anonymization needs the schema (it walks each recorded query's selections
+to know which values are enums, dates, ids...). Variables are NOT
+anonymized — they're the replay matching key; don't record with secret
+variables.
+
+## When to use what
+
+- **FakeClient** — no recording needed; schema-correct random data.
+  Best default for unit tests.
+- **Cassettes** — real response *shapes* from a real API (pagination
+  quirks, actual union members, servers' null habits). Best for
+  integration-ish tests and regression pinning.
+- **Anonymized cassettes** — cassette fidelity, committable without PII.

data/docs/errors.md

@@ -30,7 +30,8 @@ it failed:
 | `TransportError` | never reached the server — DNS, connection refused, TLS, timeout |
 | `ServerError` | reached it, non-2xx HTTP — `#status`, `#body` |
 | `QueryError` | 200 body with top-level GraphQL errors — `#errors`, `#data`, `#extensions`, `#codes` |
-| `ValidationError` | build time: the query didn't validate against the schema (also an `ArgumentError`) |
+| `TypeError` | the response wouldn't cast into the generated structs — `#struct`, `#cause` |
+| `ValidationError` | build time: the query didn't validate against the schema |
 
 ```ruby
 begin
@@ -38,22 +39,37 @@ begin
 rescue GraphWeaver::TransportError
   retry                                   # network blip
 rescue GraphWeaver::ServerError => e
-  raise if e.status < 500                 # backoff on 5xx only
+  e.status >= 500 ? backoff : raise       # retry 5xx; a 4xx is our bug
 rescue GraphWeaver::QueryError => e
   e.codes.include?("THROTTLED") ? backoff : raise
 end
 ```
 
-What counts as a `TransportError` is an **extensible set** — each transport
-seeds its own network exceptions (`Errno::*`, `SocketError`, timeouts, TLS; the
-Faraday executor adds its own), and you can register more so a custom adapter's
-or connection pool's failure gets the same treatment:
+Or skip the hand-rolling — `Retry` wraps any transport with
+configurable retries:
 
 ```ruby
-GraphWeaver.register_transport_error(ConnectionPool::TimeoutError)
-GraphWeaver.transport_errors << MyAdapter::ResetError   # it's just a Set
+transport = GraphWeaver::Retry.new(
+  GraphWeaver::Transport::HTTP.new(url),
+  tries: 5,                        # total attempts
+  backoff: :exponential,           # or :linear, or ->(attempt) { seconds }
+  base: 0.5, max: 30,              # seconds, clamped at max:
+  jitter: true,                    # randomize each delay by 50-100%
+  retry_codes: ["THROTTLED"],      # also retry GraphQL errors by code
+)
 ```
 
+Defaults match the rescue block above: transport failures always retry,
+`ServerError` only on 5xx (a 4xx is your bug — retrying won't fix it;
+override with `retry_if:`), and GraphQL-level codes only when listed in
+`retry_codes:`. Exhausting `tries:` re-raises the last error.
+
+Two deliberate exceptions live *outside* the hierarchy, because typed
+kwargs should fail like any Ruby method call: a wrong-typed variable
+raises sorbet-runtime's `TypeError` ("Parameter 'page': Expected type
+T.nilable(Integer), got type String"), and a missing required variable
+raises a plain `ArgumentError` ("missing keyword: :id").
+
 Business/validation failures returned *as data* (Shopify-style `userErrors { field
 message code }`) aren't errors here — they're just fields you selected, so they
 deserialize onto `response.data` like anything else and you inspect them there.
@@ -61,6 +77,18 @@ deserialize onto `response.data` like anything else and you inspect them there.
 The one-shot `GraphWeaver.execute` / `execute!` mirror this: `execute` returns
 the envelope, `execute!` the result-or-raise.
 
+## Extending TransportError
+
+What counts as a `TransportError` is an **extensible set** — each transport
+seeds its own network exceptions (`Errno::*`, `SocketError`, timeouts, TLS; the
+Faraday transport adds its own), and you can register more so a custom adapter's
+or connection pool's failure gets the same treatment:
+
+```ruby
+GraphWeaver.register_transport_error(ConnectionPool::TimeoutError)
+GraphWeaver.transport_errors << MyAdapter::ResetError   # it's just a Set
+```
+
 
 ## Programmatic surfacing
 
@@ -102,5 +130,5 @@ When wire data disagrees with the types the schema promised at generation time
 (a nil where non-null was declared, a malformed scalar, an unknown enum value),
 casting raises `GraphWeaver::TypeError` naming the failing generated struct,
 with the original exception as `#cause`. Simulate one in tests with
-`FakeExecutor.new(schema:, corrupt: "Person.birthday")` — see
+`GraphWeaver::Testing::FakeClient.new(schema:, corrupt: "Person.birthday")` — see
 [testing](testing.md).

data/docs/generated_modules.md

@@ -4,6 +4,101 @@
 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/
+    inputs.rb        # manifest: requires + forward declarations
+    inputs/          # one file per shared type (input structs, enums)
+    *_query.rb       # one module per query — 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
+```
+
+The conventional paths are lists (entries may be globs — the default
+includes `app/graphql/*/generated`, so per-schema layouts load too).
+Append extra locations (a test-only schema, an engine's queries) and
+every loader walks them all:
+
+```ruby
+# e.g. in spec/support/graph_weaver.rb
+GraphWeaver.generated_paths << "spec/support/graphql/generated"
+GraphWeaver.queries_paths << "spec/support/graphql/queries"
+```
+
+The singular accessors (`generated_path` etc.) read and replace the
+first entry — the default target for `generate!` and the rake tasks.
+
+(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
@@ -21,9 +116,9 @@ module PersonQuery
     const :person, T.nilable(Person)
   end
 
-  def self.executor ...          # default transport (see below)
-  def self.execute(id:, executor: self.executor)   # -> GraphWeaver::Response[Result]
-  def self.execute!(id:, executor: self.executor)  # -> Result, or raises QueryError
+  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
 ```
 
@@ -46,40 +141,97 @@ 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 serialize themselves
+- 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** generate module-level `T::Struct`s with `serialize`
-(aliased as `to_h`) producing the wire hash — optional fields default nil and
-stay off the wire:
+**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
-input = AdoptQuery::AdoptionInput.new(name: "Rex", species: AdoptQuery::Species::Dog)
-AdoptQuery.execute!(input:)
+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):
 
-# or pass a plain hash straight to execute — .coerce normalizes and type-checks it at
-# the boundary (underscored Symbol/String keys; enums accept wire values;
-# nested inputs accept hashes)
-AdoptQuery.execute!(input: { name: "Rex", species: "DOG" })
+```ruby
+AdoptQuery.execute!(input: { name: "Rex", species: "DOG" }, detail: true)
 ```
 
-Nested inputs work (dependencies emit first); recursive input types are not
-yet supported.
+In the generate! workflow, input types (and the enums they use) are
+emitted **once per schema** — one file per type under
+`generated/inputs/`, with `inputs.rb` as the manifest. The module is
+named from the output path: the conventional layout gets
+`GraphQLInputs`, while a multi-schema layout names each schema's module
+after its directory (`app/graphql/github/generated` → `GithubInputs`).
+Override globally with `GraphWeaver.inputs_module=` or per run with
+`generate!(inputs_module:)`; opt out with
+`generate!(shared_inputs: false)`. Per-type files keep schema drift
+reviewable: a migration diffs exactly the types it touched, and types
+the schema drops are pruned on regeneration (`verify` flags strays).
+Query modules alias what they touch,
+so `AdoptQuery::AdoptionInput` still works and shared types keep one
+identity across modules — three filtered Hasura queries cost one ~11k-line
+inputs file plus ~90 lines each, instead of ~35k lines of duplicates.
+Deeply nested types live unaliased in the shared module
+(`GraphQLInputs::PetFilter`). Dynamic `parse` stays self-contained.
+
+The structs themselves are module-level (`AdoptQuery::AdoptionInput`):
+typed consts plus a compact per-field `FIELDS` table that the
+`GraphWeaver::InputStruct` runtime drives — `serialize` (aliased `to_h`)
+produces the wire hash with nil optionals omitted, `coerce` builds from
+plain hashes. The conversions ship in the generated file as data
+(lambdas in the table), so a Hasura `bool_exp` pulling hundreds of input
+types stays ~2 lines per field instead of unrolled methods. 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** — each abstract selection site emits a module:
-  one member struct per possible type, `Type = T.type_alias { T.any(...) }`,
-  and a `from_h` dispatching on `__typename`. Generation *requires*
-  `__typename` in the selection so dispatch is possible.
+- **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`);
@@ -92,19 +244,16 @@ are impossible).
 Nested struct names come from GraphQL type names, disambiguated one level by
 field name on collision.
 
-## Executors
-
-An executor is anything with `execute(query, variables:)` whose result `to_h`s
-into `{"data" => ..., "errors" => ...}`. Resolution order:
+## Clients
 
-1. per call: `execute(..., executor: something)`
-2. per module: `PersonQuery.executor = something`
-3. baked constant: `Codegen.generate(..., executor: MyApi::Executor)`
-4. global: `GraphWeaver.executor` (raises helpfully when unconfigured)
+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
-global — that's also what lets [testing's auto_fake](testing.md) swap in a
-fake per example.
+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
 

data/docs/getting_started.md

@@ -0,0 +1,136 @@
+# 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"
+
+GraphWeaver::Testing.configure { |config| config.auto_fake = true }
+```
+
+The opt-in is deliberate (no surprise fakes); once on, the schema
+auto-locates from the committed dump and 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.*`
+— 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

@@ -1,30 +1,31 @@
 # Against a real API
 
-Everything composes for a remote endpoint — introspect the schema
-straight off the wire, then query with typed results. GitHub's API,
-end to end:
+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"
 
-executor = GraphWeaver::HttpExecutor.new(
-  "https://api.github.com/graphql",
-  headers: { "Authorization" => "Bearer #{`gh auth token`.strip}" },
-)
-
-# introspecting a big API takes seconds — cache: stores the introspection
-# JSON in a file and reuses it for ttl: seconds. For Rails.cache/redis,
-# cache SchemaLoader.introspection_result(executor) (a plain Hash) instead.
-schema = GraphWeaver::SchemaLoader.introspect(
-  executor,
-  cache: "tmp/github-schema.json",
-  ttl: 24 * 60 * 60,
-)
+# 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)
-GraphWeaver.register_scalar("DateTime", type: Time, serialize: :iso8601, requires: "time")
+# 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 = GraphWeaver.parse(schema:, executor:, query: <<~GRAPHQL)
+RepoQuery = github.parse(<<~GRAPHQL)
   query($owner: String!, $name: String!) {
     repository(owner: $owner, name: $name) {
       nameWithOwner
@@ -40,7 +41,13 @@ 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`).
-