graph_weaver 0.4.6 → 0.5.0

data/REVIEW.md

@@ -0,0 +1,946 @@
+# Library review — 2026-09-05
+
+A six-agent review of graph_weaver 0.4.6: codegen/runtime corner cases, fresh-install
+DX against a live public API, Apollo Federation coverage, transport/performance, a
+competitive analysis of the field, and a survey of what users of peer libraries
+actually complain about.
+
+Sibling of `PLAN.md` (the roadmap) and `NOTES.md` (the research notebook). This is the
+findings document: what's broken, what's missing, and what the field says is worth
+building. Items are marked **PROVEN** (a repro was run) or **REASONED** (argued from
+code or spec, not executed). Findings verified independently a second time are marked
+**✓verified**.
+
+Baseline at review time: 308 examples green, `srb tc` clean, tree clean.
+
+---
+
+## 1. The one-paragraph version
+
+The library is in better shape than its version number suggests, and its instincts are
+right: query-driven codegen, a typed error envelope, a real testing harness, and schema
+lifecycle management are four of the seven structural problems of this category, and
+graph_weaver has independently landed on good answers to all four — while under-selling
+every one of them. The defects worth fixing are concentrated and specific: one silent
+data-corruption bug in union narrowing, one documented-but-absent nullability behaviour,
+a federation loader that rejects the artifact teams actually have, a default HTTP
+transport that serializes every request in the process, and one measured violation of
+its own stated "generate only what the query touches" invariant that produces 5,386
+lines for a two-condition query. Fix those and the remaining gaps are features, not
+faults.
+
+---
+
+## 2. Confirmed bugs
+
+Ranked by severity. These are the implementation backlog.
+
+### B1 — Narrowing + `__typename` silently casts members into the wrong struct
+**PROVEN ✓verified · HIGH · `codegen.rb:416`, `codegen/nodes.rb:260-262`**
+
+When a selection narrows to a single type condition (`... on Person { … }`) *and* also
+selects `__typename`, codegen still takes the narrowing branch. But narrowing's
+"this isn't my type" test is *did the object come back empty?* — and selecting
+`__typename` guarantees it never is.
+
+```ruby
+query { search(term: "el") { __typename ... on Person { email } } }
+# emits: v3.empty? ? nil : Person.from_h(v3)
+
+Result.from_h("search" => [{ "__typename" => "Person", "email" => "d@e.f" },
+                           { "__typename" => "Pet" }])
+# => [Result::Person __typename="Person" email="d@e.f",
+#     Result::Person __typename="Pet"     email=nil]   # <- a Pet, typed as a Person
+```
+
+If the member has a non-null field you get a confusing `TypeError: key not found`.
+If its fields are all nullable you get **silent corruption**. This is the exact shape
+of a federation `_entities { __typename ... on Widget { … } }` query, and "always
+select `__typename`" is a widespread habit.
+
+`docs/generated_modules.md:252` claims narrowing "skips the dispatch (and the
+`__typename`) entirely" — the code allows it anyway.
+
+**Fix:** when `__typename` is present, dispatch on the tag rather than on emptiness:
+`data["__typename"] == "Pet" ? Pet.from_h(data) : nil`. Strictly better than the
+emptiness heuristic, and it removes the need for the `unconditional_field?` guard in
+this case.
+
+### B2 — `@skip`/`@include` on a fragment doesn't make its fields nilable
+**PROVEN · HIGH · `codegen.rb:471-475`, `selection.rb:42-53`**
+
+Directive handling inspects *field* nodes only; `Selection#each_field` recurses into
+inline fragments and named spreads without carrying their directives down. Fields
+reached through a conditional fragment keep non-null typing and get `data.fetch(...)`.
+
+```ruby
+query Q($s: Boolean!) { people { id ... on Person @skip(if: $s) { name } } }
+Result.from_h("people" => [{ "id" => "1" }])
+# => GraphWeaver::TypeError: key not found: "name"
+```
+
+Identical for a named spread with a directive. Directive-on-a-spread is legal GraphQL
+and the ordinary way to make a whole block conditional; the README advertises
+"`@skip`/`@include` nullability" without qualification.
+
+**Fix:** thread a conditional flag through `each_field` so `object_node` strips
+`NonNull` for anything under a conditional fragment. `FakeClient` and `Anonymizer` walk
+the same `Selection` module, so they stay in step for free.
+
+### B3 — Abstract types generate a struct per schema member, not per selected condition
+**PROVEN ✓verified · HIGH · `codegen.rb:693`**
+
+`union_members` maps over `@schema.possible_types(type)`. Measured against the GitHub
+schema already committed at `examples/github/schema.json`, where `Node` has 278
+possible types:
+
+```
+query GetThread($id: ID!) {
+  node(id: $id) {
+    __typename
+    ... on PullRequestReviewThread { isResolved }
+    ... on Issue { title }
+  }
+}
+```
+
+→ **5,386 lines / 193 KB**, 278 `T::Struct`s of which **275 hold nothing but
+`const :__typename, String`**, and a `T.any` with 278 members. Generation itself is
+fast (0.021s); the cost is checked-in volume, `srb tc` load, PR reviewability, and a
+`T.absurd` exhaustiveness story that is unwritable at 278 branches.
+
+This violates the stated invariant in `CLAUDE.md` — "codegen is query-driven … only for
+the types a query actually touches" — in exactly one place. It has an exact twin in the
+wild: [genqlient #416](https://github.com/Khan/genqlient/issues/416), and The Guild
+conceded the same disease in
+[graphql-codegen v6](https://the-guild.dev/graphql/hive/blog/graphql-codegen-client-v6-202604)
+("large generated files filled with types you never use").
+
+**Fix:** emit a member struct only for types the selection actually names, plus **one**
+catch-all `Other` carrying the interface-level fields. This answers the maintainer
+objection raised on genqlient #416 ("the server can still return a type you have no
+fragment on") and mirrors the shape of its PR #419. `T.absurd` becomes writable *and
+stays writable* when the schema grows a type. Add a spec asserting generated size is
+O(named conditions), not O(possible types) — the bound is the feature.
+
+### B4 — A schema-level directive makes a supergraph unloadable
+**PROVEN ✓verified · HIGH · `schema_loader.rb` (`strip_federation`)**
+
+Any directive on the `schema` definition — `@tag`, `@composeDirective`, or a
+`@composeDirective`'d custom SCHEMA directive — produces:
+
+```
+GraphQL::ParseError: Expected LCURLY, actual: DIRECTIVE ("directive") at [4, 1]
+```
+
+Root cause is in graphql-ruby's printer, isolated:
+
+```ruby
+GraphQL.parse('schema @foo { query: Query } directive @foo on SCHEMA type Query { hi: String }')
+  .definitions.first.to_query_string
+# => "schema\n  @foo"     <- directives printed, `{ query: Query }` body omitted
+```
+
+`SchemaDefinition#to_query_string` omits the root-types body when root type names are
+the GraphQL defaults but still prints retained directives, so the reprint emits a
+braceless `schema @tag(...)`. `@link`/`@core` are stripped, so current specs never hit
+it; anything else on `schema` does. The error's line number refers to a document the
+user never wrote.
+
+**Fix:** strip *all* directives from the `SchemaDefinition` node (codegen never reads
+them), or drop the node when root types are conventional.
+
+### B5 — Subgraph SDL cannot be loaded at all
+**PROVEN · HIGH · `schema_loader.rb`**
+
+A raw subgraph schema — from `rover subgraph fetch`, `_service { sdl }`, or the
+`.graphql` in a service repo — dies with an unbranded
+`NoMethodError: undefined method 'get_argument' for an instance of GraphQL::Schema::LateBoundType`.
+
+This is the artifact teams most often have, and it is the *only* way to type an
+`_entities` query, since `_entities`/`_service` are deliberately absent from a
+supergraph.
+
+**Fix (proven in probe):** detect a subgraph SDL and prepend the federation directive
+definitions it references but doesn't define. Add `subgraph_sdl?` alongside
+`federation_sdl?` plus a `SUBGRAPH_DIRECTIVE_DEFS` constant; inject only definitions not
+already present. Both fed-1-style and `@link`-style subgraphs loaded cleanly once
+definitions were injected.
+
+### B6 — Result enums and variable enums are incompatible types
+**PROVEN ✓verified · MEDIUM · `codegen.rb:454-462` vs `codegen.rb:745-746`**
+
+A result field's enum builds a fresh nested `EnumNode`; the same GraphQL enum as a
+variable registers in `@variable_enums` (hoisted to `GraphQLInputs`). Nothing reconciles
+them.
+
+```
+result enum class:   M1::Result::Pet::Species
+variable enum class: M1::Species
+equal?               false
+round-trip: TypeError: Parameter 'species': Expected T.any(M1::Species, String),
+            got M1::Result::Pet::Species
+```
+
+Reading a value out and feeding it back — echoing a filter, re-submitting a status — is
+an obvious move and fails at both `srb tc` and runtime. Found independently by two
+agents from opposite directions (reading the emitter; hitting it live after a mutation).
+
+**Fix:** when a result field's enum is also a variable type in the same module, reuse
+the shared `@variable_enums[name]` node.
+
+### B7 — Enum-in-a-list variables reject wire strings
+**PROVEN · MEDIUM**
+
+`docs/generated_modules.md:179` states unconditionally that enum variables "accept the
+enum or its wire value". True for a scalar enum, false inside a list:
+
+```ruby
+execute!(type: "ANIME")                            # works
+execute!(type: "ANIME", sort: ["POPULARITY_DESC"]) # NoMethodError: undefined method 'serialize' for String
+```
+
+```ruby
+"type" => (type.is_a?(MediaType) ? type : MediaType.deserialize(type)).serialize,   # coerces
+variables["sort"] = sort.map { |v1| v1&.then { |v2| v2.serialize } }                # doesn't
+```
+
+Sorbet's runtime doesn't deep-check array elements, so the sig doesn't catch it either;
+the user gets a raw `NoMethodError` naming neither the variable nor the enum.
+
+**Fix:** emit the same `is_a? ? : .deserialize` inside the map, widen the element type.
+
+### B8 — Cassette recording is broken for the call the docs show
+**PROVEN ✓verified · MEDIUM · `testing/cassette.rb:133`**
+
+`docs/cassettes.md:13` shows `Cassette.use("github", client: live)`. Passing a `Client`
+— which the kwarg name invites and the doc demonstrates — fails:
+
+```ruby
+c = GraphWeaver::Testing::Cassette.use("anilist", client: live)
+SearchMediaQuery.execute!(c, search: "x", type: "ANIME")
+# ArgumentError: missing keywords: :search, :type
+```
+
+`Recorder` calls `@client.execute(query, variables:)`, but `Client#execute` is
+`execute(query, **variables)` — the one-shot surface, not the transport contract. So
+`variables:` is swallowed as a kwarg named `variables`. This is the duck-typed-client
+invariant leaking: every other call site unwraps via `GraphWeaver.resolve_transport`;
+the recorder forgot.
+
+**Fix:** `@client = GraphWeaver.resolve_transport(client)` in `Recorder#initialize`.
+
+### B9 — Global registrations are never validated, so typos silently no-op
+**PROVEN ✓verified · MEDIUM · `codegen.rb:383-387`**
+
+`validate_registrations!` iterates only the client-scoped `@enums`/`@scalars`/`@types`.
+The global registries — the path `getting_started.md` step 3 explicitly recommends — are
+never walked.
+
+```ruby
+GraphWeaver.extend_type("Medai", MediaHelpers)   # typo
+GraphWeaver.generate!                            # SUCCEEDS. Helper never applied. No warning.
+```
+
+The good error already exists and fires only on the client-scoped path:
+`extend_type("Medai") matches no type in this schema — did you mean 'Media'?`
+
+**Fix:** walk the global registries too.
+
+### B10 — Two result keys that underscore to the same prop emit an unloadable file
+**PROVEN · MEDIUM · `codegen.rb:402`**
+
+`prop = underscore(key)` with no collision check — the exact check added for variable
+kwargs in v0.4.6. Generation succeeds; the file can't be loaded.
+
+```ruby
+query { person(id: "1") { name Name: name } }
+# => ArgumentError: Attempted to redefine prop :name
+```
+
+Reachable with a plain alias; no exotic schema needed.
+
+**Fix:** mirror the variable-collision check in `object_node`.
+
+### B11 — Output props aren't checked against reserved names
+**PROVEN · MEDIUM · asymmetry with `codegen.rb:766-770`**
+
+`input_node` validates props against Ruby keywords and generated methods; output structs
+validate nothing. A GraphQL field named `class`, `hash`, `send`, `to_h` or `freeze`
+generates a file that raises at `require` time. Fields named `class` are not
+hypothetical.
+
+**Fix:** run the same reserved-name check on output props, raising at generation with a
+suggestion to alias in the query.
+
+### B12 — A multi-operation document silently types only the first operation
+**PROVEN · MEDIUM · `selection.rb:22`**
+
+`load_operation` takes `.first`, `emit_module` puts the *whole* document in `QUERY`, and
+no transport sends `operationName`. So a file holding two operations types one and sends
+a request the server must reject with "Must provide operation name". Several operations
+per file is a common habit.
+
+**Fix:** raise at generation when the document holds more than one `OperationDefinition`
+(the small, honest change), or plumb `operationName` through — see F4.
+
+### B13 — `from_response` lets malformed envelopes escape as raw Sorbet `TypeError`
+**PROVEN · MEDIUM · `emit.rb:485-493`**
+
+v0.4.6 branded the transport-level malformed-body cases, but `from_response` is
+documented public API and is unguarded. A non-Hash `data`, a Hash `errors`, an array of
+strings for `errors`, and a non-Hash `extensions` all escape the `GraphWeaver::Error`
+umbrella.
+
+**Fix:** shape-check in the emitted `from_response`.
+
+### B14 — `spec/integration/federation_spec.rb:95` calls a method that doesn't exist
+**PROVEN ✓verified · LOW (test-only)**
+
+`router.executor` — `Client` exposes `transport`/`transport!`. `executor` survives only
+as a generated-`execute` kwarg. Hidden because `:integration` specs are excluded from
+the default run; with the call fixed, the spec passes against a live gateway.
+
+**Fix:** rename, and consider a CI job that at least *loads* the integration specs — a
+stale method reference survived several releases.
+
+### B15 — Smaller confirmed items
+
+| | Finding | Where |
+|---|---|---|
+| B15a | `GraphQL::ParseError` escapes unbranded — `inline_fragments` parses before `Codegen#generate`'s rescue | `codegen.rb:336,344` |
+| B15b | A custom scalar whose cast raises anything but `TypeError`/`ArgumentError`/`KeyError` escapes the umbrella (`JSON::ParserError`, `Money::ParseError`) | `emit.rb:356` |
+| B15c | Enum values differing only in case collide into one constant (`enum E { active ACTIVE }`), raising at load not generation | `emit.rb:303` |
+| B15d | `@skip` on the narrowing inline fragment itself isn't caught by the all-conditional guard | `codegen.rb:431`, `659-664` |
+| B15e | `@skip` on `__typename` breaks a dispatched union's unguarded `data.fetch("__typename")` | `codegen.rb:687`, `emit.rb:387` |
+| B15f | A field selected both conditionally and unconditionally is typed over-nilably (`any?` should be `all?`) | `codegen.rb:473` |
+| B15g | `@oneOf` input objects get no exactly-one validation | `codegen.rb:758-777` |
+| B15h | `extend_type(requires:)` isn't checked for loadability, unlike `register_scalar(requires:)`; the emitted `require` also needs `$LOAD_PATH` (true in Rails, not a plain app) | |
+| B15i | Directive-definition arguments aren't pruned by the `@inaccessible` cascade — bare `RuntimeError`. Composition almost certainly forecloses this; the defect is the unbranded error | |
+| B15j | `Hints` defines `method_missing` without `respond_to_missing?` | `hints.rb:43` |
+
+---
+
+## 3. Ergonomics, errors, and documentation
+
+Cheap, high-ratio fixes. Most are a line or two.
+
+### Documentation defects
+- **`docs/testing.md:75-79`** passes the client as a `client:` kwarg across five lines;
+  generated `execute` takes it **positionally**. The same file gets it right on line 19.
+  Highest doc-damage-per-character in the repo. **PROVEN ✓verified**
+- **`README.md:84`** — "module names derive from the operation name (`query GetPerson`
+  → `GetPerson`)" is true only for `parse` on a *raw string*. For a file — both
+  `parse(path)` and the rake task, i.e. the documented production path — the operation
+  name is ignored and it's `<FileName>Query`. `docs/generated_modules.md:310` states it
+  correctly. **PROVEN**
+- **`docs/generated_modules.md:252`** says narrowing skips `__typename` entirely; the
+  code allows it (see B1).
+- **`docs/generated_modules.md:179`** overstates enum wire-value acceptance (see B7).
+- **`docs/federation.md`** doesn't mention that federation **v1** supergraphs
+  (`@core`/`@join__owner`) load correctly — proven — and doesn't note that
+  `@inaccessible` is only subtracted on the supergraph path.
+- **`docs/cassettes.md`** references `MissingRecording` as though nested under
+  `Cassette`; it's `GraphWeaver::Testing::MissingRecording`.
+- **`schema_loader.rb:214`** recommends `.graphql` for reviewable diffs and says both
+  formats "load back identically" — true semantically, misleading on cost: **374 ms vs
+  173 ms** on GitHub's schema. One sentence fixes it.
+
+### Error messages worth improving
+- **Codegen errors never name the query file**, and drop line/col they already capture.
+  `ValidationError` populates `line`/`column` via `validation_detail` then joins only
+  `message`; `generation_plan` has `path` in scope and never passes it. Wanted:
+  ```
+  invalid query in app/graphql/queries/typo.graphql:
+    4:5  Field 'titel' doesn't exist on type 'Media' (Did you mean `title`?)
+  ```
+- **A strict `alias:` breaks unrelated queries** and the message doesn't name its own
+  fix. `optional: true` is documented and resolves it; given how consistently this
+  library puts the fix *in* the message, this one should end with
+  `— pass optional: true to skip selections that don't fit`, and say which query failed.
+- **`GraphWeaver.resolve_transport` passes anything through unchecked**, so a bad client
+  surfaces as `NoMethodError … for an instance of Hash`. A one-line guard would have
+  made the `docs/testing.md` error self-diagnosing.
+- **`rake graph_weaver:schema:refresh` can't bootstrap** and says so unhelpfully — it
+  needs the url recorded in the dump. Since `GraphWeaver.client` is already a url client
+  at that point, refresh could use it.
+- **A bare host** (`GraphWeaver.new("graphql.anilist.co")`) reports "unsupported schema
+  format"; the cause is the missing scheme. Also an `ArgumentError`, not a
+  `GraphWeaver::Error`.
+- **Unregistered custom scalars silently become `T.untyped`** with no output. For a
+  library whose pitch is exact result shapes, this deserves a line:
+  `3 unregistered custom scalars → T.untyped: CountryCode, FuzzyDateInt, Json`.
+
+### Ergonomic gaps
+- **`FakeClient` override keys aren't validated.** `@overrides.fetch("Person.nmae")`
+  silently does nothing and the test passes against random data — a test that has
+  quietly stopped pinning what it thinks it pins. `Codegen.validate_registration!`
+  already validates `Type.field` coordinates with spellchecked errors; call it from
+  `FakeClient#initialize`. Apollo Kotlin has the same problem
+  ([#4435](https://github.com/apollographql/apollo-kotlin/issues/4435), 11 reactions);
+  graph_weaver's global `Testing.configure` is already the thing they're asking for.
+- **No documented way to reach the schema inside an `auto_fake` spec** —
+  `FakeClient#schema` doesn't exist though it holds one, and `Testing.config.schema` is
+  documented only as a writer.
+- **Mutations generate `…Query` modules** — `SaveListEntryQuery.execute!` reads wrong
+  for a write.
+- **`load_queries!` silently replaces loaded constants**, so previously-built structs
+  become instances of an orphaned class and `is_a?` starts failing. Painful in a console.
+- **`Response` has no `ok?`/`success?`** — `errors?` is the idiom, but people reach for
+  the positive.
+- **`register_enum("X", Y, {…})`** (guessing a positional map) gives a bare
+  `ArgumentError: wrong number of arguments` with no hint that `map:` is the kwarg.
+
+### Packaging
+The packaged gem installs and runs clean from a scratch `GEM_HOME` — **no `s.files`
+gaps**. It does ship `CLAUDE.md`, `PLAN.md`, `NOTES.md`, `Gemfile.lock` and now this
+file; harmless, but they're internal.
+
+---
+
+## 4. Feature gaps
+
+### Federation
+
+| Item | Status | Note |
+|---|---|---|
+| Composed fed-2 supergraph SDL | works | join v0.5, `@join__implements`/`@unionMember`/`@enumValue`/`isInterfaceObject`/`overrideLabel` all strip cleanly |
+| Federation **v1** supergraph (`@core`/`@join__owner`) | works | undocumented; docs claim v2 only |
+| Router API schema / live introspection | works | integration spec passes against a real `@apollo/gateway` |
+| **Raw subgraph SDL** | **broken** | B5 |
+| **Any `schema`-level directive** | **broken** | B4 |
+| `@inaccessible` cascade | **correct** | stress-tested against Apollo's composition rules; both spec-mandated residual behaviours implemented, the one genuinely-reachable edge (inaccessible Mutation root) handled, loop terminates |
+| `@link` `import:` renames, default namespacing (`@federation__inaccessible`) | silently wrong | hidden fields survive into the API schema |
+| `federation__Scope` / `federation__Policy` / `context__ContextFieldValue` | leak into `schema.types` | any graph using `@requiresScopes`/`@policy`/`@context` — i.e. fed 2.5+ auth |
+| `_entities` representations | read side good, input side untyped | `alias: {entity: "_entities.first"}` works well; `representations:` is bare `T::Array[T.untyped]` |
+| `@defer`/`@stream` | unsupported | fails cleanly; see §7 |
+
+**F1 — Derive `@link` namespaces instead of hardcoding prefixes.** Replace
+`FEDERATION_PREFIXES = %w[join__ link__ core__]` with prefixes computed from the schema's
+own `@link`/`@core` declarations — the URL's penultimate path segment, overridden by
+`as:`, plus the `import:` list with `{name:, as:}` renames. This is precisely the
+[core spec's](https://specs.apollo.dev/core/v0.1/) API-derivation rule. **One change
+fixes four defects**: the `federation__*` leak, the `@link(as:)` leak, renamed
+`@inaccessible` being missed, and the `@core`-only leak — and it restores the invariant
+`docs/federation.md` already promises. Metadata proven reachable off the parsed
+`SchemaDefinition`. *Effort: M.*
+
+**F2 — Typed `_entities` representations.** With B5 fixed, parse `@key(fields:)` during
+subgraph load and emit a per-member builder
+(`UserQuery::Representations.user(id: "1")` → `{"__typename" => "User", "id" => "1"}`).
+Today the user hand-builds representations with no check that `__typename` is present or
+that the key field set is satisfied — both hard requirements of the subgraph spec.
+Stays within the leaf-codec/decoration invariant: this is generation, not a new
+deserializer path. *Effort: M–L; worth a design note first.*
+
+**F3 — Brand `SchemaLoader` failures under `GraphWeaver::Error`.** v0.4.6 made "malformed
+inputs stay branded" an invariant; the loader violates it on every federation-shaped
+failure — `NoMethodError`, `GraphQL::ParseError`, `InvalidDefaultValueError`, bare
+`RuntimeError`. Pairs naturally with B5: *"this looks like a subgraph SDL; weaver can
+load it, but you fed it as X."* *Effort: S.*
+
+### Transport
+
+**F4 — Send an `Accept` header and `operationName`.** **PROVEN by wire capture.** Both
+transports send only `Content-Type: application/json`; net/http supplies `accept: */*`.
+The [GraphQL-over-HTTP draft](https://graphql.github.io/graphql-over-http/draft/) says a
+conforming client **MUST** send `application/graphql-response+json`. So a spec-conformant
+server has no signal to use the newer media type and we stay on legacy status-code
+semantics forever. Add a real `User-Agent` in the same change — server operators
+currently can't attribute traffic.
+
+`operationName` is never sent either, so every request is anonymous in Apollo Studio,
+Hasura, and every APM that keys traces on it. Codegen already knows the name; emit it as
+a constant beside `QUERY` and widen the contract to
+`execute(query, variables:, operation_name: nil)` — the optional kwarg keeps the
+duck-typed slot intact, and `Schema.execute` happens to accept `operation_name:` too.
+*Effort: header, an hour; operationName, ~1 day (ripples to FakeClient/Cassette/Retry).*
+
+**F5 — Connection pool in `Transport::HTTP`.** **PROVEN ✓verified.** `@mutex.synchronize`
+wraps the entire round trip, so one transport = one in-flight request process-wide — and
+`GraphWeaver.client = api` is the documented pattern. Measured against a 10 ms-latency
+server, 8 threads × 5 calls: **488 ms shared vs 72 ms with 8 transports (~6.8×)**. A
+prototyped `SizedQueue` pool of 5 gave **1152 ms → 291 ms (4.0×)** at 8 threads × 10
+calls. Invisible on localhost because the penalty scales with *server latency*, not CPU.
+~40 lines, entirely inside `transport/http.rb`'s private section, plus a `pool_size:`.
+*Effort: ~0.5 day. Highest-value transport item.*
+
+**F6 — Faraday timeouts and passthrough.** Faraday is **auto-selected** on
+`defined?(::Faraday)` — and Faraday rides in transitively via stripe/octokit — so most
+Rails apps get it without choosing it. It opens **a connection per request** (20 TCP
+accepts for 20 requests) and `Transport::Faraday.new` takes no timeout knobs, leaving
+net/http's **60 s/60 s** — 6× and 2× the documented `Transport::HTTP` defaults, on the
+transport you're more likely to get. `GraphWeaver.new(url, …)` exposes no
+`open_timeout:`/`read_timeout:` at all. A missing timeout is an outage, not a slowdown.
+Also consider preferring `:net_http_persistent` when loadable, or logging which adapter
+was auto-picked. *Effort: ~0.5 day.*
+
+**F7 — In-process is a second-class citizen.** **PROVEN.** Correct, but blind:
+- **No `context:`** — `Schema.execute` accepts one, nothing supplies it. A resolver
+  reading `context[:current_user]` gets `nil` and it surfaces as
+  `Cannot return null for non-nullable field Query.me`. For server-side composition,
+  context *is* the request.
+- **Zero logging** — all logging lives in `Transport#execute`, which an in-process
+  schema bypasses entirely. Not one line at DEBUG.
+- **Errors unbranded** — a resolver raise surfaces as raw `RuntimeError` in-process vs
+  `GraphWeaver::ServerError` over HTTP, so `rescue GraphWeaver::Error` catches one and
+  misses the other.
+
+A ~50-line `GraphWeaver::InProcess` wrapper closes all three (verified working), wired
+into `Client#initialize` so `GraphWeaver.new(MySchema, context: {…})` works. Logging
+belongs to the client slot, not to `Transport` — this is the right home. *Effort: ~0.5 day.*
+
+**F8 — Preserve the HTTP response.** `Transport::HTTP#post` returns `[status, body]`;
+`ServerError` carries `status`/`body` only; `Retry` has **zero** references to
+`Retry-After` or 429. Real code monkey-patches the transport to recover headers —
+libraries.io overrides `GraphQL::Client::HTTP#execute` wholesale to capture
+`x-ratelimit-remaining` and build `rate_limited?`/`unauthorized?` predicates. Don't widen
+the duck-typed contract: add `headers` to `ServerError` (the `Net::HTTPResponse` is
+already in hand), teach `Retry` to honour `Retry-After`, and optionally expose
+`last_response_headers` on a transport. This is the difference between being
+retry-correct against GitHub/Shopify and not. *Effort: S–M.*
+
+**F9 — An instrumentation seam.** `logging.rb` is the entire observability story: no
+`ActiveSupport::Notifications`, no callback, no way for an APM to time a call or count
+errors by code. For a gem that ships a railtie, that's the notable omission.
+`GraphWeaver.instrumenter = ->(event, payload, &blk) { … }` defaulting to a no-op, called
+in `Transport#execute` and in the `InProcess` wrapper — one seam, both paths, and
+`ActiveSupport::Notifications` becomes a 2-line adapter. *Effort: ~1 day.*
+
+**F10 — `RateLimitError` / a throttle predicate.** `retry_codes: ["THROTTLED"]` exists
+and `THROTTLED` appears three times in the docs as a hand-written string; everyone
+writes this class themselves. Promote it to a named `QueryError` subclass recognizing
+common codes plus HTTP 429 once F8 lands. *Effort: XS.*
+
+**F11 — CA/mTLS knobs on `Transport::HTTP`.** Today the answer is "use Faraday", which
+is a real answer but undiscoverable. Four kwargs forwarded to `Net::HTTP.start`.
+*Effort: ~2 h.*
+
+### Category-level features
+
+**F12 — Union `fallback:` for forward compatibility.** `emit_union` generates
+`else raise … "unexpected __typename"`. An upstream team adding a union member — a
+**non-breaking** change by every schema-evolution convention — hard-fails every response
+carrying it, though your selected fields remain valid. `register_enum(…, fallback:)`
+already exists for exactly this, and `docs/scalars.md` sells it as letting responses
+"keep flowing instead of raising". Enums get forward-compatibility; unions, the more
+common evolution point in a federated graph, don't. Both Rust clients treat this as
+first-class (cynic *requires* a fallback variant). **Honest tension:** a fallback weakens
+the `T.absurd` story — with one, exhaustiveness is over *generated* members rather than
+*schema* members. That's the right trade, and it's why it must be opt-in and documented
+plainly. Note B3 largely subsumes this: the catch-all `Other` is the same mechanism.
+*Effort: S.*
+
+**F13 — Hoist shared object fragments.** Already done for **unions** (v0.4.0: a lone
+shared spread hoists into `GraphQLUnions`, aliased per query). Not for object fields, so
+`fragment PersonFields on Person` spread into three queries yields three structurally
+identical, mutually incompatible structs — a helper written against one won't typecheck
+against the others. This is the property that decides whether checked-in codegen scales
+past a dozen queries, and 80% of the machinery exists (`lone_shared_spread`,
+`generate_unions`, `shared_artifacts`, `derive_module`). genqlient reached the same
+answer via its `flatten` directive. *Effort: M, mostly test surface.*
+
+**F14 — A pagination helper.** The most-requested thing nobody in the "typed structs, no
+normalized cache" tier has shipped:
+[genqlient #357](https://github.com/Khan/genqlient/issues/357) (open since 2024-10,
+maintainer agrees, no design), graphql-codegen #5212 (24 reactions), Apollo Kotlin #3807.
+Real code hand-rolls it every time — and writes **two near-identical queries** differing
+only by `after: $cursor`, which graph_weaver already makes unnecessary (a nil variable
+is omitted from the wire).
+
+The structural advantage is real: the genqlient requester named the blocker as "the
+field name varies per query" — exactly what a *query-driven* generator knows at build
+time. Detect `pageInfo { hasNextPage endCursor }` plus a nullable cursor variable and
+emit `each_page`/`each_node` returning a lazy `Enumerator` — a shape Ruby has and Go
+argued about for two years.
+
+**The warning, stated plainly:** three ecosystems examined this and declined —
+ariadne-codegen closed [#383](https://github.com/mirumee/ariadne-codegen/issues/383) as
+"tricky to implement in a way that fits all use cases", and Apollo Kotlin *deleted* its
+pagination codegen (PR #6735). Their stated reasons (arbitrary field paths, forward vs
+backward, nested connections, `nodes` shorthand vs `edges { node }`) are not obviously
+wrong. "Nobody built it" is weaker evidence of opportunity than it looks. This is also
+the first feature that turns a generated module into a mini-runtime orchestrating several
+requests — defensible, still query-driven, but a real line to cross. Gate behind opt-in.
+**Cheap prerequisite worth doing regardless:** a `docs/pagination.md` noting that one
+query with a nullable `$cursor` suffices. *Effort: M–H, heuristic-heavy.*
+
+**F15 — Query documents validated against a refreshed schema.** Given a new schema,
+report which checked-in operations no longer validate. `Codegen#generate` already calls
+`@schema.validate(@query)` and builds per-error detail; the re-introspection machinery
+already exists for `graph_weaver:schema:verify`. Add a `graph_weaver:schema:check` task
+reporting instead of raising.
+
+Why this is more interesting than it sounds: **it answers a question Apollo's paid tier
+structurally cannot.** [GraphOS operations checks](https://www.apollographql.com/docs/graphos/platform/schema-management/checks)
+run against *historical usage metrics* — a 7-day window, a 10,000 distinct-operation cap,
+requiring a metrics pipeline — so they answer "did anyone *use* this field lately", not
+"does my repository still compile". `graphql-inspector validate` is the only
+document-driven tool and it's JS. graphql-ruby's own docs point users at
+`GraphQL::StaticValidation` and tell them to write the rake task themselves.
+*Effort: ~1 day. Best value-per-hour on this list.*
+
+**F16 — `@semanticNonNull`.** Nullability fatigue is a theme in *every* ecosystem
+(six of graphql-codegen's top-20 issues). It's measurable in this repo's own showcase:
+`examples/rick_and_morty.rb` lines 41–55 is a 15-line loop containing **5 `&.`, 2
+`.compact`, 1 `.to_a`**. `@semanticNonNull` is a *schema* directive ("null only on
+error"), which fits the model exactly — `SchemaLoader` reads it, `object_node` emits
+`String` instead of `T.nilable(String)`, `from_h` raises if a null does arrive. Sorbet is
+the type system best served by it, because `T.nilable` is *more* intrusive than TS's `?`.
+For schemas you don't own, a local override registry
+(`GraphWeaver.non_null("Person.email")`) alongside `register_scalar`.
+See [Apollo's nullability docs](https://www.apollographql.com/docs/kotlin/advanced/nullability)
+and [graphql/nullability-wg](https://github.com/graphql/nullability-wg/discussions/58).
+*Effort: M.*
+
+**F17 — Nil-vs-error, the question nobody has answered.** Relay's maintainers state it
+best, in [#4416](https://github.com/facebook/relay/issues/4416): *"An ecosystem-wide
+tradeoff (ecosystem-wide because no GraphQL client has addressed this before): discard
+queries with errors, or not be able to discern whether a null is error or not."*
+Nine years, 64 reactions on the original issue.
+
+graph_weaver is **one step away**: `Response#errors_at(path)`/`#report` already carry
+path-indexed errors with entity ids. The missing piece is going from a struct instance
+back to its path — `from_h` already knows the path as it descends. Start with a
+documented `Response#null_because_of_error?(path)` helper; even the string-based version,
+*named and documented*, is ahead of the field. *Effort: M for the honest version.*
+
+**F18 — Persisted-query manifest.** graph_weaver knows every operation at build time,
+which is exactly what makes a manifest possible — and **nothing in Ruby generates one
+from client documents** (graphql-ruby's OperationStore is GraphQL-Pro at $1,100/yr and
+server-side; the free gem is server-side too). **Design note: three manifest formats have
+converged** — Apollo's, Relay's, and graphql-codegen's — and GraphQL Hive accepts all
+three, while `rover persisted-queries publish` takes `--manifest-format apollo|relay`.
+**Emit one of those; do not invent a fourth.** The APQ runtime half fits the duck-typed
+slot exactly as `Retry` does — a client wrapping a client, `lib/graph_weaver/persisted.rb`
+beside `retry.rb`. Note APQ grants **zero** safelisting (Apollo files it under
+*performance*); safelisting requires `apq: {enabled: false}`. *Effort: M.*
+
+**F19 — `graphql.config.yml` in the docs.** Five lines of YAML, zero gem code:
+
+```yaml
+schema: app/graphql/schema.json
+documents: app/graphql/queries/**/*.graphql
+```
+
+[vscode-graphql](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql)
+(2.8M installs) **requires** a graphql-config file; the JetBrains plugin (6.1M downloads)
+reads the same one; graphql-config supports introspection JSON directly. This buys
+validation-as-you-type, field/argument autocomplete, go-to-definition into the schema and
+hover docs — for a Ruby repo, with no JS project. It also makes `graphql-inspector
+validate` and `@graphql-eslint` available over the same globs in CI. Ruby developers
+simply don't know this works. *Effort: an hour. Best value-per-line in this document.*
+
+**F20 — Per-operation codegen knobs.** Every graph_weaver knob is schema-wide (global or
+client-scoped); there is no per-query escape hatch at all. genqlient's `# @genqlient`
+directives are the model — and most of them graph_weaver already has or doesn't need
+(`bind` ≈ `register_scalar`, better; `for` ≈ the `Type.field` coordinate; `omitempty`/
+`pointer` are Go nil workarounds). Genuinely missing: **`typename`** (name the generated
+type for a field) and **`alias`** (a Ruby prop name *without* a GraphQL alias that changes
+the wire query). `examples/github/generated/stargazers_query.rb` is six levels deep with
+two distinct structs both wanting to be `Repository`; today the only rename lever changes
+what you send. *Effort: M. Papercut relief, not new capability.*
+
+**F21 — Smaller items.** A `rake graph_weaver:init URL=… AUTH=…` (the only manual step in
+an otherwise copy-paste setup is "open a Rails console and run
+`GraphWeaver.new(url, cache: true).schema`"). A shipped CLI (`bin/generate` is fixture
+tooling — long-standing PLAN item). Parse/execute memoization (~3× cost re-generating per
+call — PLAN item). Shared input structs across modules (one Hasura `bool_exp` drags ~28k
+lines into *every* module — PLAN item). Structured logging payload
+(`{event:, url:, ms:}` + a scrub hook — PLAN item). An unused-selection lint
+(`rake graph_weaver:unused`) — with checked-in structs and Sorbet, "this prop is never
+read" is statically answerable in Ruby in a way it isn't in most ecosystems, recovering
+the one real benefit graphql-client's data masking bought without its runtime error.
+
+---
+
+## 5. Competitive position
+
+*All external figures checked 2026-09-05.*
+
+**The core claim holds.** No maintained Ruby gem offers per-query static types. Three
+independent checks agree: graphql-client's
+[Tapioca compiler PR #7](https://github.com/github-community-projects/graphql-client/pull/7)
+has been stalled since 2024-11 *and* targets schema-wide RBIs rather than per-operation
+result shapes anyway; a GitHub search for Ruby + GraphQL + Sorbet returns exactly two
+repos; the other, `yogurt`, last released 2020-11-26 at 3 stars. State it with the
+caveat that makes it honest: **this idea was tried once and died** — though yogurt's own
+README concedes it lacked named fragments and that the author "probably got a lot of the
+decisions wrong", so it isn't a clean verdict on the thesis.
+
+**The market read is the most important correction this review produced.**
+graphql-client's 94.2M downloads looks like an entrenched incumbent. It isn't:
+
+- **Shopify removed it.** Gemspec diff, v9.5.1 vs current `main`: v9.5.1 declared
+  `graphql-client`; current declares `httparty`, `oj`, `sorbet-runtime` — and no
+  `graphql` or `graphql-client` at all.
+  [BREAKING_CHANGES_FOR_V10.md](https://github.com/Shopify/shopify-api-ruby/blob/main/BREAKING_CHANGES_FOR_V10.md)
+  names the reason: *"There is no need to dump the schema to a local JSON file before
+  using it anymore."* The schema-dump requirement — graphql-client's whole validation
+  model — was a stated motivation for leaving.
+- **A CI bot is a large share of what remains.** `gitlab-triage` alone is 24.1M downloads,
+  reinstalled every pipeline run. graphlient's 32.3M is a wrapper, not an independent
+  choice.
+- **Deliberate adoption today:** graphlient ~1,894/day, artemis ~173/day.
+
+So the frame is **not "a big market with a weak incumbent"** but **"a small, quiet market
+where nobody is defending the position"** — 136 Stack Overflow questions tagged
+`graphql-ruby` against 20,775 for `graphql` (~0.65%), and zero Reddit or HN threads
+discussing Ruby GraphQL client choice. Sentiment isn't negative; the topic doesn't
+register.
+
+**Strategic implication:** favour cheap, high-leverage moves over long builds. Winning an
+undefended position is mostly a distribution problem, and the payoff for a six-month
+feature programme is capped by a demand ceiling no feature will lift. F19 (an hour), F15
+(a day), the doc fixes in §3, F4 (an hour) — then spend the reclaimed time on a
+comparison page and a post aimed at Sorbet shops.
+
+**The best pitch line available:** Shopify's current SDK depends on `sorbet-runtime` and
+still returns GraphQL responses as `Hash{String, Untyped}`. A Sorbet shop, shipping a
+Sorbet-typed SDK, with untyped GraphQL — the gap drawn by the biggest vendor in the space.
+
+### Where graph_weaver wins
+Per-query static types (uncontested). Custom scalar deserialization — graphql-client has
+[an open issue](https://github.com/github-community-projects/graphql-client/issues/17)
+since 2024-02 whose workaround is monkey-patching `GraphQL::Schema::BUILT_IN_TYPES`, posted
+with a 🤢. Federation (graphql-client has an open
+[federated-router crash](https://github.com/github-community-projects/graphql-client/issues/78)).
+The error model — graphql-client currently carries
+[#67 "Network errors are discarded"](https://github.com/github-community-projects/graphql-client/issues/67)
+(a 403 surfacing as `KeyError: key not found: "data"`) and
+[#75 "Errors not populating correctly"](https://github.com/github-community-projects/graphql-client/issues/75).
+Fragments for plain reuse — graphql-client forces Relay-style data masking and users file
+[#76](https://github.com/github-community-projects/graphql-client/issues/76) asking to
+escape it. Testing. And `verify_generated!`, which genqlient — its closest peer — lacks.
+
+### Where a competitor is better
+**Institutional safety**: graphql-client is GitHub's with a decade of production use, and
+"no static types" is a cost many teams accept over "4 stars, one author, two months old".
+**graphlient is quietly the healthiest Ruby client** — 0.9.0 shipped 2026-08-02, more
+recent than graphql-client's last release — and for "call this API, don't make me think"
+it's the right answer while graph_weaver is over-engineered for the job.
+**Concurrency** (F5). **Checklist breadth** — no subscriptions, `@defer`, uploads,
+batching, persisted queries.
+
+### The honest weakest point
+**Bus factor against surface area.** ~5,500 lines, 844 in `codegen.rb` alone, one author.
+Codegen is unforgiving: the v0.4.6 changelog is a list of edge cases where generated code
+raised `NameError` at runtime, all caught in a single review sweep. That's healthy
+diligence *and* a measure of how much surface there is to get wrong. `verify_generated!`
+mitigates drift; nothing mitigates the maintainer.
+
+**Second:** the Sorbet bet has a horizon. Sorbet remains dominant, but the direction of
+travel is toward RBS, and Sorbet's own RBS comment support is experimental **and does not
+do runtime type checking** — precisely the property generated `sig`s depend on. Fine
+near-term; worth keeping the emission format pluggable rather than assuming `sig {}`
+forever.
+
+### What the field says graph_weaver already got right
+Four of the seven structural problems of this category, all under-advertised:
+
+- **Testing** is under-served *everywhere* — genqlient [#108](https://github.com/Khan/genqlient/issues/108)
+  open 5 years (wandb wrote a whole `gqlmock` package themselves), Apollo Kotlin's
+  [#6076 MegaIssue: testing utilities](https://github.com/apollographql/apollo-kotlin/issues/6076),
+  a gql.tada RFC at 11 reactions, a 22-comment confusion thread at graphql-codegen. The
+  mechanism is always identical: generation makes result types *precise*, which makes them
+  *expensive to construct by hand*, and nobody ships the fabricator. graph_weaver ships
+  the most complete answer of anything surveyed — and it's one README bullet.
+- **Schema lifecycle**: genqlient's **#1 open issue by reactions (22)** is
+  [remote-schema config](https://github.com/Khan/genqlient/issues/207), whose reporter
+  describes hand-building the exact CI job that `cache: true` +
+  `rake graph_weaver:schema:refresh`/`:verify` already is.
+- **Error handling**: the "wrapper destroys information" failure recurs in every
+  ecosystem, and real Ruby and Go code hand-rolls a 40-line error layer that
+  `Response` + `#report` + `#to_h` deletes.
+- **Determinism**: graphql-codegen has four separate issues about non-deterministic
+  output ([#5106](https://github.com/dotansimha/graphql-code-generator/issues/5106),
+  14 reactions, and friends). graph_weaver sorts throughout and generation is
+  byte-identical across runs — but this is **not stated as a guarantee anywhere**. It
+  should be, with a spec asserting it. (Also: `verify_generated!` does exact
+  `File.read == source`, so a CRLF checkout reproduces graphql-codegen's
+  [#10309](https://github.com/dotansimha/graphql-code-generator/issues/10309) —
+  normalize line endings.)
+
+**The competitive story is not "typed structs" — everyone has those. It's "typed structs
+*and* you can test them *and* the schema keeps itself honest."**
+
+---
+
+## 6. Performance and maintainability
+
+Measured on Apple Silicon, Ruby 3.4, laptop with other things running; ratios trustworthy,
+absolute ms ±10–20%.
+
+**Codegen is linear and a non-issue.** ~9–11 µs per field selection, flat across a 16×
+range in width and 13× in depth; fragment spreads likewise linear. Real-world: 0.02s for
+the pathological 278-type case in B3. **No O(n²) anywhere.** Any refactor of the AST walk
+can be judged purely on readability.
+
+**The hot runtime path is proportionate — and the brief's premise was wrong.**
+`from_h` costs ~1.8 µs/struct, linear across three orders of magnitude. Where it goes:
+
+- **58% garbage collection** (sweeping + marking), driven by ~6 objects and 2.3 hashes
+  per struct — inherent to `T::Struct` keyword construction.
+- **Sorbet sig checking is only ~6%**, not the bottleneck. Disabling runtime sig checks
+  entirely saved 6%. The real Sorbet cost is `T::Props`' per-prop setter validation,
+  which that flag doesn't govern — and even that is ~0.83 µs of the 1.80. A plain
+  `Struct` is 0.29 µs, so **`T::Struct` costs ~0.54 µs/struct over plain — that is the
+  price of the product, and it's the right price.**
+- **`Date.iso8601` is 25% of `from_h`** on a query with one date per three structs — the
+  largest *addressable* slice, and it's a docs fix: `register_scalar` with an explicit
+  cheaper `cast:` beats the inferred regexp-based `Date.iso8601`.
+
+End to end over localhost, 600 structs: casting is 81% of 1.32 ms — which says "casting
+adds ~1.1 ms of CPU", not "the gem is slow". Against a real 30 ms API call it's ~3%.
+**Recommendation: do nothing** for typical queries; it matters only for a 10,000-row
+report (55 ms) or a 50,000-row export (284 ms).
+
+**Schema loading is the one Rails number worth knowing.** GitHub's 2.87 MB dump:
+`SchemaLoader.load(.json)` **173 ms**; the same schema as SDL **374 ms** (2.2×). A cached
+schema is fully re-parsed every boot — the cache saves the round trip, not the parse. But
+the production path pays **0 ms**: the railtie only `require`s generated `.rb` files and
+`client.schema` is lazy. You pay it in dev consoles and CI `verify_generated!`. Worth
+documenting, not worth engineering around.
+
+**Memory is clean** — 2 heap slots retained after 10× a 15,000-struct cast. **Per-request
+allocation is 9 objects / 1.1 µs** with nothing to hoist; the `rescue` splat is lazily
+evaluated (0 calls on 1000 successes). One real waste — `log_tag` runs a regex over the
+whole query whenever a logger merely *exists*, costing +1.32 µs/request at `:info` for a
+tag nothing prints — is **0.004% of a 30 ms call and not worth a commit.**
+
+### Maintainability
+The decomposition is principled; don't undo it. `nodes.rb` is genuinely good — a new leaf
+kind is a new class implementing five methods and `emit.rb` doesn't change.
+
+**Load-bearing complexity, leave alone:** `object_node`'s five-way kind dispatch (all four
+abstract-type branches draw names from the same `taken` pool and the ordering between them
+is semantic — splitting it turns one readable decision table into four coupled files); the
+string-append emitter (you can grep a line of *generated output* and land on the line of
+`emit.rb` that produced it — for a code generator that beats elegance); `Emit` reading
+eight ivars off the host (all "state of one generation run"; revisit only with a second
+emission target).
+
+**Worth doing:**
+- **R1 — extract `codegen/aliases.rb`** (~130 lines). The alias subsystem has its own
+  vocabulary and touches the rest through exactly one seam (`node.aliases =
+  resolve_aliases(node)`). Same extraction already made for scalars and enums, so it's
+  consistent rather than novel. *1–2 h, mechanical, spec-covered.*
+- **R2 — `build_variables(operation)`** (~25 lines out of `generate`'s 72), leaving
+  `generate` reading as a seven-line pipeline. *30 min.*
+- **R3 — a `QueryModule` mixin** for the identical ~15-line untyped `@client` plumbing
+  repeated in every generated file. Precedent and rationale already in
+  `input_struct.rb:11-16`. **Scope limit:** `execute`/`from_response` must stay generated —
+  their sigs *are* the product. *~0.5 day; regenerates every fixture.*
+
+**Explicitly churn:** rewriting the emitter as templates/AST; strategy objects for
+`object_node`; promoting codegen to `# typed: strict` (CLAUDE.md forbids it and the
+measurement backs the policy); splitting `emit.rb` further.
+
+---
+
+## 7. Explicit non-goals
+
+Worth recording as decisions rather than omissions.
+
+- **`@defer`/`@stream`.** The spec ratified a
+  [September 2025 edition](https://spec.graphql.org/September2025/) — its first since 2021
+  — and incremental delivery **was not in it**; it's on its third or fourth attempt (PRs
+  #742 and #1034 closed as superseded, #1110 still Stage 2 Draft after six years). Apollo
+  Client 4.1 ships **two mutually incompatible handlers** for two wire formats. And in
+  Ruby, `@defer` is GraphQL-Pro only at $1,100/yr, so a Ruby client would rarely meet a
+  Ruby server that supports it. Implementing this in 2026 means betting on one of two
+  unratified formats. Failing cleanly — which it does — is the right level of support.
+- **Subscriptions.** A persistent duplex transport, a different response lifecycle, and an
+  execution model a request-scoped Rails process doesn't have. Unchecked on
+  graphql-client's 1.0 TODO since 2024 with essentially no user pressure. Rejecting at
+  *generation* time, as today, is the best possible failure. Make it a **stated non-goal**
+  so it reads as a decision, not an omission.
+- **File uploads.** Apollo removed built-in support in Server 3.0 on CSRF grounds
+  (`multipart/form-data` POSTs without a preflight); the spec repo has been frozen since
+  2025-03.
+- **Normalized caching.** Apollo's `InMemoryCache`, urql's Graphcache and Relay's store all
+  solve *component-graph consistency* — several components rendering the same entity, a
+  mutation updating it, all re-rendering without a refetch. A Ruby backend has no component
+  tree, no long-lived client-side store, and usually a request-scoped process. You'd import
+  normalization, GC, cache policies and a class of staleness bugs to solve a problem the
+  deployment shape doesn't have. `Rails.cache` around `execute` is the right size. *(Marked
+  as inference: no authoritative source states this directly.)*
+- **Fragment masking.** The evidence is unusually direct: graphql-client **already has it**
+  and users file issues asking to escape it. Masking enforces component data-colocation in
+  a component UI framework; graph_weaver's callers are services and jobs. graph_weaver's
+  shared fragments are the feature graphql-client users are asking *for* — adding masking
+  would convert an advantage into their complaint. **The mistake to avoid is being talked
+  into it.**
+- **Watch mode.** graphql-codegen's watch complaints exist because JS builds are slow and
+  the loop is long. graph_weaver generated the pathological case in 0.021s, and
+  `client.parse`/`load_queries!` already provide a no-build-step dev mode — the gql.tada
+  escape hatch, from inside a codegen tool. Say that in the docs and move on.
+- **Batching / multiplex.** Doesn't fit the one-query-per-module design; would need a new
+  `Batch` object. Skip unless demand appears.
+- **`near-operation-file` layout.** Colocation is a *component-tree* concern that pays in
+  React. In Rails, queries live in one directory and the flat layout is correct.
+- **Formalizing the client slot as a Sorbet interface.** Already in `CLAUDE.md`; the
+  research supports it. A graphql-ruby `Schema` class satisfies the contract without
+  inheriting anything, and that's what makes `FakeClient`, `Failure.*`, `Sequence` and
+  `Cassette` compose. `Retry` is a client wrapping a client; so should an APQ decorator be.
+- **A "replace a composite's deserializer" path**, even though genqlient's `bind` can bind
+  composite types. It can because a Go struct's shape is fixed by its type; a composite's
+  shape here varies per query, so binding one is correct for exactly one selection.
+- **Generating the whole schema.** genql is the cautionary example — artifact size scales
+  with schema, not query count; its prebuilt SDKs run to 19.7 MB. Query-driven codegen is
+  why a supergraph's `join__*` types emit nothing.
+
+---
+
+## 8. Recommended order
+
+**Tier 1 — correctness, do first.**
+B1 (silent corruption) · B4, B5 (federation loader) · B2 (documented behaviour absent) ·
+B6, B7 (enums) · B8, B9 (silent no-ops) · B14 (dead spec) · the `docs/testing.md` and
+`README.md:84` fixes in §3.
+
+**Tier 2 — the measured wins.**
+B3 (5,386 → tens of lines; also largely subsumes F12) · F5 (connection pool, ~4×) ·
+F4 (`Accept` + `User-Agent`, an hour; then `operationName`) · F6 (Faraday timeouts — a
+missing timeout is an outage) · F7 (`InProcess` wrapper: context, logging, branded errors).
+
+**Tier 3 — cheap leverage, disproportionate payoff.**
+F19 (`graphql.config.yml`, an hour) · F15 (`schema:check`, a day) · F3, F10, B15 items ·
+the error-message and docs work in §3 · state determinism as a guarantee and normalize
+line endings in `verify_generated!` · reposition testing and schema-lifecycle as headline
+features rather than single bullets.
+
+**Tier 4 — real projects, decide deliberately.**
+F1 (`@link` namespaces) · F13 (object-fragment hoisting) · F2 (`_entities`
+representations) · F8/F9 (response metadata, instrumentation) · F16 (`@semanticNonNull`) ·
+F17 (nil-vs-error) · F18 (persisted manifest) · F14 (pagination — read its warning first) ·
+R1–R3.
+
+---
+
+## 9. Method and provenance
+
+Six parallel Opus agents, each required to prove claims by execution rather than
+inspection, working read-only against a green baseline (308 examples) with scratch probes
+outside the repo. The tree was verified byte-identical after every agent.
+
+Findings marked **✓verified** were independently re-run by the coordinating session:
+B1 (the mis-typed `Pet`), B3 (5,386 lines / 275 vacuous structs — the agent reported 278;
+the precise count is 275 vacuous, 2 real, 1 incidental), B4 (the braceless `schema @foo`
+reprint), B6 (the enum round-trip `TypeError`), B8, B9, B14, and F5's mutex scope.
+
+Two findings were reached **independently by two agents from opposite directions** — B6
+(from reading the emitter; from a live mutation round-trip) and the missing `Accept`
+header (from a raw-socket wire capture; from reading both transports). Independent
+corroboration raises confidence materially.
+
+Calibration notes worth keeping: the perf agent **disproved the brief's premise** that
+Sorbet sig checking dominates casting cost (it's 6%), and recommended *doing nothing* on
+the hot path. The federation agent separated defects that Apollo's composition rules make
+**unreachable** from ones that hit real users, and confirmed the `@inaccessible` cascade —
+the thing most expected to break — is correct. The competitive agent argued **against its
+own earlier draft** on market size after checking Shopify's gemspec directly. Reports that
+only confirm the hypothesis they were given are worth less than these were.
+
+External figures checked 2026-09-05; every external claim in §5 and §7 carries a citation
+in the source reports.