graph_weaver 0.5.0 → 0.6.0

data/CLAUDE.md

@@ -1,161 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## What this is
-
-A typed GraphQL client for Ruby: generates `# typed: strict` Ruby (nested
-`T::Struct`s + a typed `execute`) from your queries, checked against the schema
-at generation time. Sorbet is core to the product.
-
-## Design principle — correct and simple, in that order
-
-Adoption follows delight, and delight follows from a tool that solves the real
-problem without making you think. So the bar for any change is: is it correct,
-and is it the *simplest* thing that is correct? Complexity is not neutral — it
-is confusion, bugs, and frustration, paid for by every future reader and user.
-
-What this means when choosing between designs:
-
-- **One rule beats a rule with exceptions.** A behavior you can state in a
-  sentence, and predict without reading the source, is worth more than one that
-  is marginally more capable. Generated class names come from the response key —
-  full stop — rather than from the type name with disambiguation-on-collision,
-  because the second rule can't be stated without describing its own edge cases.
-- **Prefer removing a decision to adding a knob.** The transport default got
-  *better* by deleting auto-detection: one less thing to know, one less way to be
-  surprised, and the fast path became the default. Reach for a config option only
-  after the simple default has actually failed someone.
-- **A convention can beat a capability.** One file holds one operation. That's a
-  convention, and it makes module naming derivable from the filename; supporting
-  multiple operations per file would be more capable and worse.
-- **No spooky action at a distance.** Behavior should follow from the code in
-  front of you, not from what else is in the Gemfile, what ran first, or which
-  selection the walk happened to reach earlier.
-- **Match the ecosystem's conventions** where one exists — a familiar shape costs
-  the user zero learning, which is the cheapest simplicity available.
-- **Errors are part of the interface.** A good message names what went wrong,
-  where, and what to do about it. `optional: true` in the message beats the same
-  advice buried in docs. The best bug fix often makes an error impossible; the
-  next best makes it self-explanatory.
-- **Refuse rather than guess.** When intent is ambiguous, fail loudly at
-  generation time. A silent wrong answer is the most expensive outcome this
-  library can produce, because the generated code looks authoritative.
-
-When simplicity and capability genuinely conflict, say so out loud and pick
-deliberately — but the default is simple.
-
-**Docs are a complexity detector.** A section that belabors a topic is usually
-not a writing problem — it is the library pushing complexity onto the reader.
-Before expanding an explanation, ask whether the thing being explained should
-exist. If two paragraphs are needed to say which of two ways applies, delete one
-of the ways; the docs then shrink on their own, which is the signal the cut was
-right.
-
-## Sorbet typing policy — type by value, not for coverage
-
-Sorbet being core does **not** mean every file should be `# typed: strict`. Type
-where it pays off in developer experience; leave the rest at `# typed: true`.
-
-- **Strict (full sigs) — developer-facing contracts.** The types users touch:
-  `response.rb` (the envelope every `execute` returns), the error hierarchy
-  (`errors.rb`), and the **generated code** (emitted `# typed: strict`). Concrete
-  types here give downstream apps real call-site checking + autocomplete — that's
-  the product.
-- **`# typed: true` (loose) — dynamic / boundary internals.** The codegen
-  (`codegen.rb`, `codegen/nodes.rb`, `codegen/emit.rb`, `codegen/scalar_type.rb`,
-  `codegen/enum_type.rb`, `codegen/type_helpers.rb`) walks graphql-ruby's
-  approximately-typed AST and builds modules/strings dynamically; `client.rb`
-  wraps a graphql-ruby schema and a duck-typed transport. Strict here is ~all
-  `T.untyped` — paperwork that documents shape without catching anything.
-  **Don't promote these to strict.**
-- Rule of thumb: if a sig would be mostly `T.untyped`, it isn't worth writing.
-  Concrete types = value; `T.untyped` sigs = paperwork.
-- `railtie.rb` / `tasks.rb` are `# typed: ignore` (Rails/Rake DSL).
-
-## Design invariants (don't "fix" these)
-
-- **The client slot is duck-typed.** A transport, `Retry`, a live graphql-ruby
-  schema class, or a test fake all satisfy one contract —
-  `execute(query, variables:) => {"data" => ..., "errors" => ...}` — with no
-  shared base class. **Don't formalize it as a strict Sorbet interface**: a
-  graphql-ruby `Schema` class fits the slot without inheriting anything, and a
-  strict interface would exclude it. This is why the transport/client seams stay
-  loosely typed.
-- **Codegen is query-driven.** Structs are generated per selection set, only for
-  the types a query actually touches — not the whole schema (so extra schema
-  types, e.g. federation `join__*`, generate no code).
-- **Leaf codecs vs composite decoration.** `register_scalar` / `register_enum`
-  *define/replace* how a leaf deserializes (its Ruby shape is fixed);
-  `extend_type` only *decorates* a generated composite struct with mixins — it
-  can't replace one, because a composite's shape varies per query. Don't add a
-  "replace a composite's deserializer" path.
-
-## Green before commit
-
-`bundle exec` needs the rvm ruby — the default PATH ruby is 2.6 and can't even
-load bundler:
-
-```sh
-source ~/.rvm/scripts/rvm && rvm use 3.4.9
-```
-
-Then:
-
-```sh
-bundle exec rspec              # full suite
-bundle exec srb tc             # Sorbet typecheck (CI gates on this too)
-bundle exec ruby bin/generate  # regenerate fixtures — must leave the tree clean
-```
-
-All three must pass. Sorbet sigs are runtime-checked by sorbet-runtime, so a
-wrong sig surfaces as an rspec failure, not only a `srb tc` error — a green suite
-validates the sigs against real usage.
-
-Two more when the change could reach them:
-
-```sh
-bundle exec rspec --order rand:1        # and a couple of other seeds
-bundle exec ruby bin/federation-diff    # the fixture supergraph still composes
-```
-
-Order-independence is worth checking rather than assuming — four order-dependent
-failures have hidden behind the default `:defined` order, and a *burst* of them
-usually means one shared resource cascading rather than many bugs.
-
-## Drive it from a throwaway app when the host seam changes
-
-**The suite cannot test the gem's relationship with its host.** It is not a Rails
-app, so anything that depends on Rails' boot order, Zeitwerk, or rake's task
-graph is structurally invisible to it — and both bugs found that way were silent
-in development and only appeared in production boot or when registrations
-mattered:
-
-- `rake graph_weaver:generate` never ran `:environment`, because the task asked
-  `Rake::Task.task_defined?("environment")` at *load* time and Rails defines it
-  *after* railties' `rake_tasks` blocks. Every `register_scalar`/`extend_type` in
-  an initializer was silently dropped at generation, and `verify` reported the
-  result up to date.
-- `app/graphql/generated` sits under a Zeitwerk root while its files define
-  top-level constants, so eager loading raised `NameError`. Lazy dev boot was
-  fine; production was not.
-
-So when the railtie, the rake tasks, the generator, or the documented install
-path changes, spin up a scratch Rails app outside the repo, point its Gemfile at
-your checkout, and actually use it. Worth exercising: **both** a remote endpoint
-and the app's own graphql-ruby schema in-process; `RAILS_ENV=production` boot and
-`rails zeitwerk:check`; a registration in `config/initializers` that must reach
-generated output; the rake tasks end to end; and the testing harness from inside
-the app's own specs. The app is disposable — rebuilding it is cheaper than the
-bugs it catches.
-
-## Version bumps
-
-Bump `lib/graph_weaver/version.rb` and, in the **same commit**:
-
-- update `Gemfile.lock` (the gem pins its own version there; CI runs a frozen
-  `bundle install`, which fails at the *setup* step with exit code 16 — before
-  tests — if the lock is stale), and
-- add a `CHANGELOG.md` entry.
-
-`gem push` (the actual RubyGems release) is a separate, manual step.

data/DECISIONS.md

@@ -1,309 +0,0 @@
-# Decisions
-
-Roads not taken, and why. The code shows what was chosen; it is silent about
-what was considered and rejected — and those are the ones that get re-litigated,
-usually by someone with the same good instinct that was already followed to its
-end once.
-
-Only entries where the rejected path is *tempting* belong here. An obvious call
-needs no record. What changed and when lives in `CHANGELOG.md`; the invariants
-and principles live in `CLAUDE.md`; stated non-goals (subscriptions, `@defer`,
-uploads, normalized caching, fragment masking, batching) live in `REVIEW.md` §7.
-
----
-
-## The client slot stays duck-typed
-
-**Considered:** formalizing `execute(query, variables:, operation_name:)` as a
-Sorbet interface or a base class, so the thing every client implements is
-declared rather than implied.
-
-**Rejected because** a live graphql-ruby `Schema` class satisfies the slot and
-cannot inherit from us. An interface would exclude the one implementation we
-neither wrote nor control — and that implementation is the whole in-process
-story. The openness is the feature.
-
-Downstream of this: `Parsing` requires `#schema` of its includers and can't
-declare it, hence one `T.unsafe(self)` in that mixin.
-
-## `InProcess` lives outside `Transport::`
-
-**Considered:** moving it under `Transport::`, or restructuring so
-`Transport::HTTP` parents a native and a Faraday implementation and `InProcess`
-slots in beside them.
-
-**Rejected because** `Transport` is a base class, not a namespace: it owns the
-GraphQL-over-HTTP flow (encode the body, classify network failures, `ServerError`
-on non-2xx, parse). `InProcess` implements none of that. And the restructure
-wouldn't achieve its goal anyway — a bare `Schema` class is in the client slot
-too, so `Transport::` still wouldn't mean "things you can pass as `transport:`".
-The taxonomy can't be clean because the slot is deliberately open.
-
-Renaming the abstract base (`Transport::Base`) to stop it sharing a name with its
-namespace is the smaller, honest version if this ever itches again.
-
-## `Transport::HTTP` is the default; Faraday is opt-in
-
-**Considered:** keeping the previous `defined?(::Faraday)` auto-detection.
-
-**Rejected because** Faraday arrives transitively through stripe, octokit and
-friends, so adding an unrelated gem silently changed your transport, your
-timeouts, and your connection reuse (Faraday's default adapter reconnects per
-request; measured 10 connections for 10 requests versus 1). Behaviour that
-depends on what else is in the Gemfile is unreasonable-about-able. Same code,
-same transport.
-
-## Cassettes live in `spec/cassettes`, not `spec/fixtures`
-
-**Considered:** `spec/fixtures/`, or a namespaced `spec/fixtures/graph_weaver/`,
-as the more conventional home for test data.
-
-**Rejected because** Rails globs the fixture path for `{**,*}/*.yml`
-(`active_record/test_fixtures.rb`) — recursively, so a subdirectory doesn't save
-you. `fixtures :all` would try to load cassettes as ActiveRecord fixtures. The
-conventional-looking choice is the broken one.
-
-## Directories organize queries; they don't namespace modules
-
-**Considered:** deriving module names from nested query directories, so
-`admin/pets.graphql` becomes `AdminPetsQuery` instead of colliding with
-`pets.graphql`.
-
-**Rejected because** it *moves* collisions rather than removing them —
-`admin/pets.graphql` and `admin_pets.graphql` would then collide — so the
-refusal has to exist either way, and the naming rule stops being statable
-without describing which path segments count. A duplicate base name refuses,
-naming both files.
-
-## `#parse` requires a schema, so `Retry` doesn't have it
-
-**Considered:** delegating `#parse` through `Retry` to whatever it wraps, so
-`Retry.new(client).parse(q)` reads naturally.
-
-**Rejected because** `respond_to?(:parse)` would then be true half the time and
-false the other half — a `Retry` over a bare HTTP transport has no schema to
-reach through to. The rule is "anything holding a schema can parse against it",
-which is a domain, not an exception. `Retry` doesn't meet the precondition.
-
-## Mutations generate `…Mutation` modules
-
-**Considered, and initially rejected:** keeping the uniform `…Query` suffix,
-because renaming breaks call sites *and* because the generated filename changes,
-leaving a stale `_query.rb` that `load_generated!` keeps requiring.
-
-**Reversed once generated-file pruning landed** — the stale-file half of the
-objection dissolved, and the remaining "one rule beats a conditional one"
-argument lost to `SaveListEntryMutation.execute!` being what a user types every
-day. The generated filename mirrors the constant, so `ls generated/` still
-answers "what's the constant".
-
-## One shared types module, not three
-
-**Considered:** keeping `GraphQLInputs`, `GraphQLUnions` and `GraphQLEnums`
-separate on the grounds that their file shapes genuinely differ (a manifest plus
-per-type files versus a single file).
-
-**Rejected because** file layout is an implementation detail and the constant a
-user types is not. Merging also *deleted* a mechanism: the artifacts used to
-alias each other's constants across files, which lexical scope now handles for
-free. Per-type files were extended to all three rather than dropped — adding an
-enum value diffs one file.
-
-## Subgraph mapping is derived, then verified — never guessed
-
-**Considered:** requiring an explicit `subgraphs:` map, on the grounds that
-auto-detection is guessing and a wrong guess silently points a test suite at the
-wrong resolvers.
-
-**Rejected because** matching on *what a schema defines* against the routing
-table is a derivation with evidence, not a guess — and the ambiguous cases
-(two candidates, or none) refuse rather than pick. Detection and validation are
-the same check run in two directions, so there is no second code path to
-disagree.
-
-## Only some `ArgumentError`s were branded
-
-**Considered:** two uniform answers. Brand all ~50 `raise ArgumentError` sites
-under `GraphWeaver::Error`, so "everything descends from `Error`" is literally
-true; or leave subgraph detection's refusals as `ArgumentError` and qualify the
-sentence in `docs/errors.md`.
-
-**Rejected because** the first throws away the one thing `ArgumentError`
-communicates — you passed something wrong at this call site, like any Ruby
-method — and `pool_size: must be >= 1` is exactly that. The second leaves the
-refusals a `Testing::Router` user actually meets outside the umbrella the docs
-point them at, which is where a spec helper rescues.
-
-What survives is a line that can be stated: **what the library concludes,
-having read your schema, is a `GraphWeaver::Error`; an argument wrong on its
-face is an `ArgumentError`.** Subgraph mapping (`ConfigurationError`) and a
-query file whose name can't spell a constant are verdicts; `cast:` not being a
-Symbol is not. A rule with a stated boundary beats a uniform one that lies
-about half its cases.
-
-## An abstract type is bucketed on `__typename`, not planned away
-
-**Considered:** keeping the `abstract_boundary` refusal, on the reasoning that a
-representation needs one concrete `__typename` and the planner — which takes no
-variables and runs before any fetch — cannot know it.
-
-**Rejected because** the planner doesn't have to know it. It only has to plan
-*every* possibility: the supergraph says which concrete types a subgraph can
-answer a union or interface with, so the plan carries a branch per type and
-execution picks the one the data came back as. Deciding at execution is the
-existing precedent — `@skip`/`@include` already filter deferrals against the
-variables in hand for exactly the same reason.
-
-The corollary is smaller and sharper than the rule it replaced. A fragment
-whose condition can't hold at a position — `... on Note` where the answering
-subgraph's union holds no Note — is **dropped**, not refused, even though
-"refuse rather than guess" pulls the other way. It isn't a guess: the fragment
-can never match, so `{}` is the only answer, and a real `@apollo/gateway`
-returns exactly that. What still refuses is the case where the supergraph
-genuinely doesn't say — no `@join__unionMember`/`@join__implements`, and the
-type in more than one subgraph — because then the branch list itself would be
-invented.
-
-## A nested field set crosses whole, or not at all
-
-**Considered:** assembling a nested `@key`/`@requires` object from more than
-one fetch — `store { id }` from the subgraph in hand and `store { region
-{ code } }` from a prefetch, deep-merged into one representation. It is what
-`@apollo/gateway` does internally (`deepMerge(entity, dataReceivedFromService)`),
-and it would close the last nested case rather than refusing it.
-
-**Rejected because** the only shapes that produce the split are ones where the
-gateway is no longer an oracle. A field set reaching *through* a key field is
-the common one, and there the gateway doesn't split at all: composition drops
-`@external` from key fields — an entity's key is answerable by any subgraph
-declaring it — so the extending subgraph looks able to resolve the whole path,
-the gateway satisfies the `@requires` locally, and gets back whatever that
-subgraph happens to hold. Merging would mean answering *better* than the
-gateway, which under `0 wrong` is the same failure as answering worse. So a
-root fed by two fetches refuses, naming both halves and where each comes from.
-
-That trap is also why the fixture graph's nested `@requires` walks a plain
-external field (`dimensions`) and not the nested `@key`'s object (`store`):
-the first is diffable against a real gateway, the second isn't.
-
-## The in-process router refuses rather than approximates
-
-**Considered:** planning every query shape, falling back to a best-effort answer
-where the semantics are uncertain.
-
-**Rejected because** a test double that answers 5% of queries differently from
-production is worse than one that answers 80% and declines the rest loudly. The
-refusal boundary *is* the product. Non-null propagation is the concrete reason:
-before that pass existed, three queries returned silently wrong data where the
-real router returned `data: null`.
-
-A corollary: a `--strict` mode for the drift differ was built and then deleted,
-because once a partly-local supergraph became a supported setup, failing on any
-skipped subgraph was wrong for every graph except a fully-local one — and that
-one's report already says "checked 3 of 3".
-
-## `federation:diff` fails when it checked *nothing*
-
-**Considered:** leaving zero-checked as a pass, on the `--strict` reasoning
-directly above — absence is supported, and the headline already says "checked 0
-of 4".
-
-**Rejected because** zero is not a small number of subgraphs, it is a different
-kind of answer: the gate would pass whatever the subgraphs said, so a green run
-carries no information at all. "Checked 3 of 4" did real work. And the failure
-that produced it was silent — Rails leaves `rake_eager_load` false, so a stock
-app's CI gated on nothing while printing honest prose. There is no setup where
-you'd deliberately run this task against a supergraph none of whose subgraphs
-are here; the abort says to drop it from CI if that's really you.
-
-The rule stays statable in one sentence: it fails when it found drift, and when
-it had nothing to look at.
-
-## Output structs allow Ruby-keyword prop names
-
-**Considered:** narrowing the ban to types with a registered `alias:` whose path
-starts at the prop.
-
-**Rejected because** the ban turned out to be unnecessary, not merely too broad.
-All 33 producible keywords construct, deserialize and typecheck as props; the
-only bare read is an `alias:` delegator's first hop, which now spells
-`self.next`. The proposed narrowing would also have made generation depend on
-unrelated global registry state.
-
-## Queries directories are a list again
-
-**Considered:** leaving `queries_path` singular, as 0.4.x made it — one
-`generate!` run reads one directory against one schema, and a second entry
-would produce modules at runtime that `rake graph_weaver:generate` never
-generated and `verify` never checked.
-
-**Rejected because** that failure was the *divergence*, not the plurality:
-back then `load_queries!` walked the list and `generate!` read only its first
-entry. Every reader now goes through `GraphWeaver.query_files`, so a second
-directory is generated, verified and loaded alike — and a duplicate module
-name across two directories refuses, as it already did within one. What
-survives is the honest half of the argument: one run reads one *schema*, so
-`schema_path` stays singular.
-
-## Deferred, deliberately
-
-- **`write_timeout` on `Transport::HTTP`** — a real gap (nothing bounds sending),
-  but not yet worth a kwarg. Note `open_timeout` *is* the connect timeout and
-  covers the TLS handshake too (`net-http`'s `ssl_socket_connect(s, @open_timeout)`);
-  `ssl_timeout` is the OpenSSL session timeout and not a handshake deadline.
-- **A `net_http:` passthrough hash** — the answer if the timeout/TLS kwarg list
-  keeps growing. Deliberately a hash and not a block: the pool creates
-  connections lazily and on failure, so a block would run an unpredictable number
-  of times. Configuration survives that; behaviour doesn't.
-
-## Coercion says *whether*, never *how*
-
-**Considered:** keeping `coerce: <Symbol>` (`register_scalar("ID", String, coerce: :to_s)`),
-which let a registration name the conversion as well as opt into it.
-
-**Rejected because** it asked the user to answer a question the library already
-answers — the conversion for every scalar that has one is derived from the
-scalar itself, and a custom scalar's conversion is its `cast:`/`serialize:`
-pair. Its documented showcase existed only to re-enable something deliberately
-removed from the auto path: the feature arguing for its own removal.
-
-**Also considered:** dropping the `Int`/`Float` conversion entirely, leaving
-parse as the single coercion mechanism. **Rejected because** `first: params[:page_size]`
-arriving as a String is the most common real coercion in a Rails app, and
-without it `auto_coerce` would loosen nothing among the built-ins but `Date` —
-capability loss wearing simplicity's clothes.
-
-`coerce:` and `auto_coerce` both survive because they are one question at two
-scopes — a global default with a local override, the standard shape.
-
-## `config.schema` refuses a subgraph rather than splitting in two
-
-**Considered:** splitting the setting, since it serves two masters — the schema
-fakes are fabricated against, and the live class `:in_process` runs. In a
-federated app you can't have both, and setting one to make `:in_process` work
-silently repointed `:fake` at a fraction of the graph.
-
-**Rejected because** the split is a second knob plus a rule about which one
-applies, and it buys a capability nothing lost: `:router` runs a subgraph's
-real resolvers too, stitched. The two masters only want different objects in a
-federated app, so refusing a subgraph class is the smaller change that makes
-`config.schema` mean one thing again — and the refusal `:in_process` already
-raises ("a federated graph has no one schema class — tag those examples
-`graphql: :router`") becomes the whole story instead of half of it.
-
-## The `graphql:` tag names a mode; a client is built in the example
-
-**Considered:** letting the tag carry a client — `graphql: Failure.throttled`,
-or `graphql: FakeClient.new(overrides: …)` — which reads well and would make
-the tag's value a description rather than the cleanup marker it had become.
-
-**Rejected because** metadata is evaluated when the file loads: one client
-object would be shared by every example in the group, built before
-`Testing.configure` had run. Spooky at a distance, and stateful — `#requests`
-would accumulate across examples.
-
-What the reading was right about was the leak underneath, and that is fixed
-elsewhere: `GraphWeaver.client` is snapshotted and restored around *every*
-example, so the tag no longer earns its keep as a cleanup marker, and building
-a client is a plain assignment in a `before` block. `graphql_fake(**options)`
-exists only because a fake needs the schema derivation the tag was doing.

data/Makefile

@@ -1,23 +0,0 @@
-.PHONY: check generate test tc integration docs
-
-# full verify loop: regenerate, test, typecheck
-check: generate test tc
-
-# manual/one-off checks against real GraphQL APIs (network; GitHub needs
-# `gh auth login` or GITHUB_TOKEN; federation boots an Apollo gateway — node)
-integration:
-	INTEGRATION=1 bundle exec rspec spec/integration
-
-generate:
-	bundle exec ruby bin/generate
-
-test:
-	bundle exec rspec
-
-tc:
-	bundle exec srb tc
-
-# preview what rubydoc.info will render
-docs:
-	bundle exec yard doc
-	open doc/index.html

data/NOTES.md

@@ -1,182 +0,0 @@
-Research notes — graphql-client exploration → GraphWeaver
-======
-
-**What this is now:** a working prototype of a standalone, Sorbet-typed
-GraphQL client for Ruby — "graphql-codegen for Ruby". `.graphql` queries +
-a schema (live class, introspection JSON, or SDL) generate `# typed: strict`
-Ruby: nested `T::Struct`s, casting code, and a typed `execute`, so `srb tc`
-sees the exact shape of every query result. It is **not** a graphql-client
-extension: generated code depends only on `graphql` (generation time) and
-`sorbet-runtime` (runtime); transport is a pluggable `executor:` (in-process
-schema or the bundled `HttpExecutor`).
-
-Start with `PLAN.md` for current state and next steps. Key files:
-`lib/struct_codegen.rb` (the generator), `queries/` → `bin/generate` →
-`lib/generated/` (the build loop), `StructCodegen.load` (build-free dynamic
-mode for development).
-
-**How it got here:** the repo began as an exploration of
-[graphql-client](https://github.com/github-community-projects/graphql-client)
-internals — could its class-generation layer be swapped to emit custom
-classes? (Yes: the `StructTypes` spike below.) The per-query codegen
-approach then outgrew graphql-client entirely, and everything below the
-next heading is preserved as the lab notebook: findings in chronological
-order, each backed by a spec.
-
-The specs are the documentation — each one asserts an observed behavior:
-
-```sh
-bundle exec rspec
-```
-
-## Findings, in exploration order
-
-- The client runs fine against an in-process schema: `GraphQL::Client.new(schema: Schema, execute: Schema)` — no HTTP involved.
-- Each query selection gets its own dynamically generated wrapper class (subclass of `GraphQL::Client::Schema::ObjectClass`); fields are snake_case readers, and unselected fields raise instead of returning nil.
-- **Custom scalars are deserialized automatically** when the client is built from a live schema class: the reader casts wire values through the scalar's `coerce_input` (e.g. `"1990-06-15"` → `Date`). This is the built-in hook for producing rich Ruby values.
-  - Caveat: this only works with `schema:` as a live schema class. A schema loaded from an introspection JSON dump has no coercion logic, so scalars would stay raw.
-- `to_h` returns the raw wire values (strings), not the casted ones — hydration code should read via the typed readers, not `to_h`.
-- Hydrating into `T::Struct`s is straightforward manually; the interesting next step is generating the structs (or a generic hydrator) from the parsed query definition, since the client already knows each selection's shape and types.
-
-## Swapping the class-generation layer (answered: yes)
-
-`lib/struct_types.rb` + `spec/struct_types_spec.rb` prove the generation layer
-can be replaced wholesale — the client deserializes straight into generated
-`T::Struct`s, no `ObjectClass` involved.
-
-How the pipeline hangs together (graphql-client 0.26.0):
-
-- `Client#initialize` builds the types module: `@types = Schema.generate(schema)`
-  (`attr_reader :types`, no setter — swap via `instance_variable_set` or a subclass).
-- `Client#parse` → `Definition#initialize` calls
-  `client.types.define_class(definition, ast_nodes, type)` and stores the result
-  as `definition.schema_class`. This is the ONLY thing the client asks of the
-  types module.
-- `Client#query` → `definition.new(data, errors)` → `schema_class.new(data, errors)`.
-- Everything below that is the `cast(value, errors)` protocol, composed
-  recursively per the query selection (NonNull/List wrappers, scalars, objects).
-
-So the replacement contract is just:
-- `define_class(definition, ast_nodes, type)` returning casters
-- casters respond to `cast(value, errors)`
-- the top-level caster must satisfy `Definition#new`'s case dispatch, which
-  tests `===` against the `GraphQL::Client::Schema::ObjectType` module —
-  including that module in your caster class is enough, plus a
-  `new(data, errors)` method
-
-Gotchas found:
-- the client injects `__typename` into every selection (`QueryTypename`), so a
-  custom generator must skip/handle `__`-prefixed fields
-- scalar casting reuses the schema type's `coerce_isolated_input` — same hook
-  the stock `ScalarType` uses
-- prop nullability comes for free from the type walk: everything is
-  `T.nilable` unless wrapped in NON_NULL
-
-## Sorbet
-
-- `sorbet` + `tapioca` are set up (`bundle exec srb tc` is green); rbis in `sorbet/rbi/gems`
-- `struct_types.rb` typechecks at `# typed: true`
-- generated structs are real `T::Struct`s: schema-derived prop types
-  (`T.nilable(Date)`, `T::Array[StructTypes::Pet]`) and runtime type
-  enforcement on bad wire data
-
-## Codegen: srb tc sees query result types (answered: yes)
-
-`lib/struct_codegen.rb` goes one step further than the runtime swap: it
-emits plain `# typed: strict` Ruby source from a query + schema — nested
-`T::Struct` classes, fully generated `from_h` casting code (no runtime
-reflection), and a sig'd `execute`.
-
-- source of truth: `queries/*.graphql`; regenerate with `bin/generate`
-  into `lib/generated/`; a spec asserts the checked-in output is current
-- queries are validated against the schema at generation time
-- `srb tc` statically checks result access end to end:
-  `result.person&.nmae` → `Method nmae does not exist on
-  PersonQuery::Result::Person`
-- custom scalar deserialization is inlined by the generator
-  (`Date.iso8601(...)`) via a scalar registry; nullability and list
-  casting come from the NON_NULL/LIST walk
-- note: generated `execute` runs against the schema directly, replacing
-  graphql-client at runtime entirely — the client's remaining value here
-  would be its HTTP adapter, which the generated code could target instead
-
-## Fragments & unions (answered for codegen)
-
-`queries/search.graphql` + `lib/generated/search_query.rb` exercise the
-design:
-
-- inline fragments and named fragment spreads are flattened into their
-  matching member's selection (exact type-name condition match; interface
-  conditions still open)
-- unions emit a module per selection site: one `T::Struct` per possible
-  type, a `Type = T.type_alias { T.any(...) }`, and a `from_h` that
-  dispatches on `__typename` — codegen refuses union selections that
-  don't select `__typename`
-- every possible type gets a member struct even without a fragment (it
-  still carries `__typename`), so dispatch is total
-
-## Introspection / __type metadata
-
-- `__type` / `__schema` queries work against the demo schema as expected
-  (see `spec/introspection_spec.rb` for the shapes)
-- the key result: `GraphQL::Schema.from_introspection(Demo::Schema.as_json)`
-  produces a schema that codegen runs against **byte-identically** — so
-  generation works for remote APIs known only via an introspection dump.
-  Custom scalar handling survives because the codegen scalar registry is
-  keyed by type *name*, unlike runtime `coerce_input` which needs the live
-  schema class (the caveat that broke graphql-client's scalar casting)
-
-## Federation / supergraph
-
-- join__/link-annotated supergraph SDL parses via
-  `GraphQL::Schema.from_definition`, and codegen runs against it
-  unchanged — the directives are transparent to result typing
-  (`spec/federation_spec.rb` generates from a mini supergraph and casts a
-  response with no live subgraphs)
-- gotcha: graphql-ruby's SDL builder does not apply directive-argument
-  defaults, so real Apollo `join v0.3` SDL (non-null defaulted args like
-  `extension: Boolean! = false`) fails to load unless those args are
-  provided or the directive defs are trimmed — a compatibility issue a
-  real tool would need to patch around
-- client-side, federation needs nothing more: you query the router like
-  any schema. The *server-side* angle (emitting `@key`/`@external` via
-  apollo-federation) is a separate exploration — potentially relevant to
-  autographql
-
-## Round 2: enums, interface conditions, loaders, dynamic mode, HTTP
-
-- **enums** generate `T::Enum` classes (`Species::Dog`), deserialized via
-  `Species.deserialize(...)` in `from_h`; values sorted so output is
-  deterministic across schema sources
-- **interface fragment conditions** (`... on Named { name }`) apply via
-  `schema.possible_types`, not just exact type-name match. Interface-typed
-  *fields* (a field returning `Named`) are still open — they'd emit like
-  unions with `__typename` dispatch
-- **SchemaLoader** accepts both formats a remote service can hand you:
-  introspection dump (`.json`) or SDL (`.graphql`/`.gql`); both generate
-  byte-identically to the live schema class
-- **dynamic mode**: `StructCodegen.load(...)` generates + evals in one
-  step — no build artifact, same runtime semantics, right for development
-  or one-off scripts. Tradeoff: the module is invisible to `srb tc`, so
-  static checking of result access needs the build step
-- **HTTP transport**: generated `execute` takes `executor:` — anything
-  with `execute(query, variables:)` returning `{"data" => ...}`.
-  `HttpExecutor` (Net::HTTP POST) runs the same generated structs against
-  a live server (`spec/http_spec.rb` proves it against a local WEBrick
-  serving Demo::Schema)
-- **directive defaults gap**: root cause found —
-  `BuildFromDefinition#prepare_directives` passes only usage-site args
-  while `Directive#initialize` validates all defined args without
-  applying `default_value`. `lib/directive_defaults_patch.rb` prepends
-  the fix; the federation spec now loads the *real* join v0.3 SDL.
-  Present in graphql 2.6.3 (latest) — worth an upstream issue/PR
-
-## Open questions
-
-- interface-typed fields (vs fragment conditions, which work)
-- ~~name collisions~~ ANSWERED: path-based won. A generated type is named
-  for the response key that selects it, so the name is a function of the
-  field's own position — no walk order, no first-come-first-served, and an
-  unrelated selection can't move it. GraphQL aliases double as the explicit
-  naming escape hatch (`pet: pets` names the struct `Pet`)
-- mutations/subscriptions (only query operations generate)