graph_weaver 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7673fd6efc0459bdb3097e73e1c3f8fe265910bfdaf349bf7a358adc1ece1830
-  data.tar.gz: f5ce9f4c484e1fb8f5eb074eaaac502ca62fb3ecf6ab90d9157a2a055e88c3b3
+  metadata.gz: a608ee344d2e8ebf8ff0e847a34005114cfd1efd5a44c7aa66ef81c457706526
+  data.tar.gz: 4622816580d4158d4b84140b85876f00582ac85521686da4417f1945cdb4c276
 SHA512:
-  metadata.gz: a75dd5a723dd52108e2f449bd1c5f0e1dc9a71065106614c57854f318024f700e16596cd4764cf9768f02d536cc040bd0554bdd75762eeba23c09b71a7051cf5
-  data.tar.gz: 377c07a20d2cf47873425c72ad84709c36555396fea1a2102c7bdc3f79e07e8e823ed9639238aecac8066f352e65599a10ae15a71013a7de3a0a4d3675bf169c
+  metadata.gz: 4d496923726cf4296f048f7f60305045aa1bfe042c007bcf10b87d34673bc451af85bf6165187e7f8a7b606dd0176ad54648c0ea504f69cb966d9addc9ba4503
+  data.tar.gz: ae5b74bd0de58a9f89fbc218e0103ab805c2b62bb5a9172bff6ebd38d890ad4804429789877b7a7c9ce343cb0d24f969fe8eb5785222736c042bc56008a2648a

data/CHANGELOG.md

@@ -1,3 +1,68 @@
+###  v0.4.0  (2026-07-28)
+- Shared unions: when a named shared fragment is the whole selection on a union
+  field (`feed { ...FeedItemFields }`), its type is hoisted once into a
+  `GraphQLUnions` module and every query that spreads it aliases the same type —
+  so a union selected across many queries is one Ruby type family (one
+  exhaustive `case … T.absurd`), not a fresh dispatch module per query. No flag:
+  the shared fragment is the opt-in. Triggers only for an exact lone spread;
+  mixing other fields, or shadowing with a query-local fragment, keeps the union
+  inlined. Module name derives from the output path (override with
+  `GraphWeaver.unions_module=`); dynamic `parse` still inlines.
+- Removed the `shared_inputs:` option from `generate!` / `verify_generated!`.
+  Directory-based generation always emits each input type once into a shared
+  module — the self-contained-module opt-out added complexity for little value.
+  Single-query `parse` / `Codegen.generate` still inline their types (there's
+  no set to share against). Only affects callers who passed
+  `shared_inputs: false`.
+
+###  v0.3.4  (2026-07-29)
+- Shared fragments: define reusable named fragments once (default
+  `app/graphql/fragments`, configurable via `GraphWeaver.fragments_paths`) and
+  spread them from any query. Each query inlines only the fragments it
+  transitively spreads, so the sent query stays self-contained. Fragment files
+  hold only fragments; names are unique across them. Works in `generate!` and
+  dynamic `parse`.
+
+###  v0.3.3  (2026-07-29)
+- Union member-type dedup: a union selected more than once on a struct now
+  collapses to one Ruby type family instead of a distinct per-field family with
+  identical members — so a consumer gets a single exhaustive
+  `case … T.absurd` across every field of that union. Structurally different
+  selections stay distinct types. (First cut: same-struct siblings; regenerate
+  checked-in modules to pick it up.)
+
+###  v0.3.2  (2026-07-29)
+- `register_scalar` accepts a `Type.field` coordinate to override how one
+  field's scalar deserializes — so the same scalar can be different Ruby types
+  across fields (`register_scalar("User.birthday", Date)` while
+  `ISO8601DateTime` stays a `Time` elsewhere). Field overrides win over the
+  scalar-name registration; both stack global-then-client. The coordinate is
+  validated against the schema (a typo'd or non-scalar field raises). Same
+  method, same signature — a `.` in the name selects the field form.
+
+###  v0.3.1  (2026-07-28)
+- `GraphWeaver.extend_t_sig` controls whether generated modules/structs emit
+  `extend T::Sig`. Default (`nil`) auto-detects a global T::Sig injection
+  (`class Module; include T::Sig`) and skips the now-redundant `extend` — so
+  generated code stays clean under rubocop's `Sorbet/RedundantExtendTSig`.
+  Force with `true`/`false`; `false` requires the global include.
+
+###  v0.3.0  (2026-07-28)
+- Renamed `register_type` to `extend_type` to disambiguate intent: it
+  *decorates* a generated struct with mixin modules/helpers — it doesn't
+  define or replace a type's deserialization (that's `register_scalar` /
+  `register_enum`, for leaf types, whose Ruby shape is fixed; a composite's
+  shape is per-query, so there's nothing fixed to replace). No deprecation —
+  the old name is dropped.
+- Invalid query input now raises `GraphWeaver::InputError` (under the
+  `GraphWeaver::Error` umbrella) instead of a raw `ArgumentError` /
+  `KeyError` / sorbet `TypeError`: an unknown or typo'd input key, a
+  missing required field, an out-of-range enum, or a wrong-typed field
+  when an input object is built from a hash through `coerce`. Carries
+  `#field` / `#struct` and a JSON-ready `#to_h` — one rescue point for
+  returning a 422 at an API boundary. Top-level *scalar* kwargs still
+  fail like any Ruby method call (sorbet `TypeError` / `ArgumentError`).
+
 ###  v0.2.2  (2026-07-22)
 - Generated modules expose from_response / from_response! alongside
   execute / execute!: deserialize a raw GraphQL response (fetched by any

data/CLAUDE.md

@@ -0,0 +1,70 @@
+# 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.
+
+## 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`) 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);
+  `directive_defaults_patch.rb` is `# typed: false` (a prepended monkeypatch).
+
+## 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
+
+```sh
+bundle exec rspec        # full suite
+bundle exec srb tc       # Sorbet typecheck (CI gates on this too)
+```
+
+Both 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.
+
+## 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/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.2.2)
+    graph_weaver (0.4.0)
       graphql (>= 2)
       sorbet-runtime
 
@@ -42,7 +42,7 @@ GEM
     google-protobuf (4.35.1-x86_64-linux-gnu)
       bigdecimal
       rake (~> 13.3)
-    graphql (2.6.6)
+    graphql (2.6.7)
       base64
       fiber-storage
       logger
@@ -99,16 +99,16 @@ GEM
     rubydex (0.2.7-arm64-darwin)
     rubydex (0.2.7-x86_64-darwin)
     rubydex (0.2.7-x86_64-linux)
-    simplecov (1.0.2)
-    sorbet (0.6.13347)
-      sorbet-static (= 0.6.13347)
-    sorbet-runtime (0.6.13347)
-    sorbet-static (0.6.13347-aarch64-linux)
-    sorbet-static (0.6.13347-universal-darwin)
-    sorbet-static (0.6.13347-x86_64-linux)
-    sorbet-static-and-runtime (0.6.13347)
-      sorbet (= 0.6.13347)
-      sorbet-runtime (= 0.6.13347)
+    simplecov (1.0.3)
+    sorbet (0.6.13365)
+      sorbet-static (= 0.6.13365)
+    sorbet-runtime (0.6.13365)
+    sorbet-static (0.6.13365-aarch64-linux)
+    sorbet-static (0.6.13365-universal-darwin)
+    sorbet-static (0.6.13365-x86_64-linux)
+    sorbet-static-and-runtime (0.6.13365)
+      sorbet (= 0.6.13365)
+      sorbet-runtime (= 0.6.13365)
     spoom (1.8.3)
       erubi (>= 1.10.0)
       prism (>= 0.28.0)
@@ -176,8 +176,8 @@ CHECKSUMS
   google-protobuf (4.35.1-arm64-darwin) sha256=d9c957df04fa89c749fa9a72a7b383eb4296efc9b2303dc6fd6fbe39c698ad6b
   google-protobuf (4.35.1-x86_64-darwin) sha256=66b62b4df00931018a692806df66393efa960d6d2b7da69735187249f950d3ee
   google-protobuf (4.35.1-x86_64-linux-gnu) sha256=c786439087512a3fbd199e9897d265b855f951d4027e218ea55e858d45969edd
-  graph_weaver (0.2.2)
-  graphql (2.6.6) sha256=7438e2036b571c884377eb1529225470ba959365f26dc47152953c213bc38c31
+  graph_weaver (0.4.0)
+  graphql (2.6.7) sha256=759755ce5819c965b6459c5039605cf2e4d876bb8ba5e03451676870ea787c45
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
   irb (1.18.0) sha256=de9454a0703a54704b9811a5ef31a60c86949fbf4013fcf244fabc7c775248e3
@@ -206,13 +206,13 @@ CHECKSUMS
   rubydex (0.2.7-arm64-darwin) sha256=f0d28bbf4153568be79b671642424750053e0bea971b60ddf5cec19bf4563990
   rubydex (0.2.7-x86_64-darwin) sha256=b002b259d118ac69de44470eff1597143318402c45630c47371f9542631447dc
   rubydex (0.2.7-x86_64-linux) sha256=dacfade9fa42ce4469618da6dac07e69d5f3ac6a313b4caced5234c8f052419a
-  simplecov (1.0.2) sha256=c6459434efe4b948b46477cc2df2faa73ab365f83a33c7c17f81262f4f7f1244
-  sorbet (0.6.13347) sha256=2830946e6efda8dc732c5d703350bed17f437fbea1ccfbef543a65e33ae445c1
-  sorbet-runtime (0.6.13347) sha256=54e7221d9f4b63f58aec79f3043752a9ba7810347c6ae0d903531591cc2d5f01
-  sorbet-static (0.6.13347-aarch64-linux) sha256=9bb60509bf9a8715d93e77cd55f96659575d81a5f47b52bd4f66b3dfe6f2182e
-  sorbet-static (0.6.13347-universal-darwin) sha256=d12678a45369dba9db724103d8badda995e66a83ae35798f68d804c46a6d3e45
-  sorbet-static (0.6.13347-x86_64-linux) sha256=5a4803d2ba4fc1964e23f3aa4073b224c345c2a72a5f5317623a4bae7ce2c8da
-  sorbet-static-and-runtime (0.6.13347) sha256=2130e3c20326948a3edd20385b444345cb7327eea9b141f373486e7c087a498d
+  simplecov (1.0.3) sha256=38ef0514f16ae7562f0d0f4df02610071115103d301b6de7dacbcc000082e39b
+  sorbet (0.6.13365) sha256=3a642fe7afb031ad670c2e6161b3d5492dd67705cbcafb132c9e87ded7ccf676
+  sorbet-runtime (0.6.13365) sha256=0657cddfd2319c9695a0b6e13aa7a7c7b093149e5589448c03b911adf1e243cb
+  sorbet-static (0.6.13365-aarch64-linux) sha256=14b7bf3a227ee102c119763158618bc6b677994cebfda2705b94bca56e4c25e1
+  sorbet-static (0.6.13365-universal-darwin) sha256=0f6033dde8a0dc7b7e72ada3ce73e1e3097843be16e473fb8bb2b8fb6199212b
+  sorbet-static (0.6.13365-x86_64-linux) sha256=f94daadcae55f2e0f7797f8fdc8a250c89ec62e11f2d41905ed6fb1e60ff708e
+  sorbet-static-and-runtime (0.6.13365) sha256=9768c114686f7cac0a6f2e222db4213887d294df6059802242ba6e4e08adbad9
   spoom (1.8.3) sha256=32871fa189bbfa49cf557a50f819f23cc9a6ceefd0346caa7a6adc193becd5dd
   tapioca (0.19.2) sha256=938731b07811aee8d23871b1aee8861d464fbaf2cfffbf79a62b0c869a5120ec
   thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73

data/README.md

@@ -113,6 +113,8 @@ api.execute!("query($id: ID!) { person(id: $id) { name } }", id: "1")
   `@skip`/`@include`, naming, clients, dynamic mode
 - **[Against a real API](docs/real_world.md)** — the exploratory tour:
   introspect a live endpoint (GitHub end to end), dynamic mode, schema caching
+- **[Federation](docs/federation.md)** — Apollo Federation: supergraph vs API
+  schema, feeding weaver a composed graph, the `@inaccessible` caveat
 - **[Transports](docs/transports.md)** — clients, the execute contract,
   Faraday, retries and backoff
 - **[Custom scalars](docs/scalars.md)** — the registry: codec inference,

data/docs/errors.md

@@ -31,6 +31,7 @@ it failed:
 | `ServerError` | reached it, non-2xx HTTP — `#status`, `#body` |
 | `QueryError` | 200 body with top-level GraphQL errors — `#errors`, `#data`, `#extensions`, `#codes` |
 | `TypeError` | the response wouldn't cast into the generated structs — `#struct`, `#cause` |
+| `InputError` | the variables wouldn't build into the generated input structs — unknown/typo'd key, missing required field, out-of-range enum, wrong-typed field — `#field`, `#struct` |
 | `ValidationError` | build time: the query didn't validate against the schema |
 
 ```ruby
@@ -64,11 +65,30 @@ Defaults match the rescue block above: transport failures always retry,
 override with `retry_if:`), and GraphQL-level codes only when listed in
 `retry_codes:`. Exhausting `tries:` re-raises the last error.
 
-Two deliberate exceptions live *outside* the hierarchy, because typed
-kwargs should fail like any Ruby method call: a wrong-typed variable
-raises sorbet-runtime's `TypeError` ("Parameter 'page': Expected type
-T.nilable(Integer), got type String"), and a missing required variable
-raises a plain `ArgumentError` ("missing keyword: :id").
+**Top-level scalar variables** fail like any Ruby method call, *outside* the
+hierarchy on purpose — passing the wrong Ruby type for a scalar kwarg is a
+programming bug, not caller input: a wrong-typed one raises sorbet-runtime's
+`TypeError` ("Parameter 'page': Expected type T.nilable(Integer), got type
+String"), a missing required one a plain `ArgumentError` ("missing keyword: :id").
+
+**Input-object variables** are the caller-input case, so they're *inside* the
+hierarchy. When you pass an input object as a hash (or struct) it's built
+through the generated `coerce`, and any problem there — an unknown/typo'd key, a
+missing required field, an out-of-range enum, a wrong-typed field — raises
+`GraphWeaver::InputError`. That's one rescue point for turning invalid input
+into a 422:
+
+```ruby
+rescue GraphWeaver::InputError => e
+  render json: e.to_h, status: :unprocessable_entity
+  # { "error" => "GraphWeaver::InputError",
+  #   "message" => "unknown key(s) for …Input: staus (did you mean 'status'?)",
+  #   "field" => "staus", "struct" => "…Input" }
+end
+```
+
+A nested filter reports the innermost input type, so the error points at the
+input that actually held the bad field.
 
 Business/validation failures returned *as data* (Shopify-style `userErrors { field
 message code }`) aren't errors here — they're just fields you selected, so they

data/docs/federation.md

@@ -0,0 +1,100 @@
+# Federation
+
+GraphWeaver generates a client for the **whole** graph, so with Apollo
+Federation you point it at the *composed* schema — the supergraph or the API
+schema — not at individual subgraph files.
+
+## The schema you feed it
+
+Three artifacts, easy to mix up:
+
+| Artifact | What it is | Feed to weaver? |
+|----------|------------|-----------------|
+| **Subgraph SDL** | one service's `.graphql`, with `@key`/`@shareable`/`extend schema @link` | No — it's a fragment of the graph, and its federation directives are declared elsewhere (imported via `@link`), so plain SDL loading rejects them |
+| **Supergraph** | the composed graph, annotated with `@join__*`/`@link` machinery | Yes — self-contained (see below) |
+| **API schema** | the supergraph with federation internals stripped — exactly what the router serves and what an introspection query returns | Yes — the exact client contract |
+
+`SchemaLoader.load` (and `Client.new(path_or_sdl)`) take the supergraph or the
+API schema as an SDL file or introspection dump; or point weaver at the router
+URL to introspect the API schema live.
+
+## Pointing weaver at a supergraph
+
+A supergraph SDL works as-is. It declares its own `@join__*`/`@link` directives
+and `join__*` types, so graphql-ruby builds it; weaver reads field types and
+args, not directives, so the join plumbing is ignored; and because codegen is
+**query-driven**, the federation-internal types generate no code unless a query
+names them (none would). Field shapes — nullability, args, enums, inputs — are
+identical to the API schema, so your generated structs are correct.
+
+The one caveat: a supergraph is a **superset** of the API schema, so weaver can
+only ever **over-permit** — it will never reject a valid query, but it won't
+flag one that selects a field the API *hides*. In practice that's exactly one
+thing: `@inaccessible`.
+
+### `@inaccessible`
+
+A federation-v2 directive marking an element as *present in the federated graph
+but removed from the public API schema*. Its common use is safely rolling out a
+change to a **shared type**: add the field to one subgraph marked
+`@inaccessible` (so composition doesn't require every subgraph to have it yet),
+roll it out to the rest, then drop the directive to publish it. (Apollo
+contracts also pair `@tag` + `@inaccessible` to build filtered API variants.)
+It's a fed-v2 feature — common in mature, multi-team graphs with lots of shared
+types, rare in small or young ones, and targeted where present (a handful of
+elements, not every field).
+
+Reading the raw supergraph, weaver would let you select an `@inaccessible`
+field — but the router serves the API schema and rejects it at runtime (a
+"field doesn't exist" error, surfaced as [`QueryError` / `schema_stale?`](errors.md)).
+So the gap is narrow (you'd have to query a hidden field on purpose) and fails
+loudly, not silently.
+
+One grep says whether it affects you at all:
+
+```sh
+grep -c '@inaccessible' supergraph.graphql
+```
+
+Zero, and the supergraph *is* the API schema for weaver's purposes — feed it
+directly.
+
+Other federation directives hide nothing from the schema:
+`@requiresScopes` / `@policy` / `@authenticated` keep the field and enforce
+access at runtime; `@tag` / `@requires` / `@provides` / `@external` are metadata
+weaver ignores.
+
+## The exact contract: the API schema
+
+To make codegen match the router precisely (no over-permit), feed weaver the
+**API schema** instead of the raw supergraph. Deriving it is a *subtraction*
+from the composed graph — not composition — done with Apollo's tooling:
+
+```sh
+rover supergraph compose --config supergraph.yaml > supergraph.graphql
+```
+
+```js
+// then, in JS, strip to the API schema:
+import { Supergraph } from '@apollo/federation-internals';
+import { printSchema } from 'graphql';
+
+const api = Supergraph.fromString(supergraphSdl).apiSchema().toGraphQLJSSchema();
+process.stdout.write(printSchema(api));   // api.graphql — feed this to weaver
+```
+
+Check the API SDL in (many teams already emit it in CI) and point weaver at it:
+codegen then validates against exactly what clients can query, with no live
+gateway involved.
+
+## Which to use
+
+- **No `@inaccessible`** → point weaver at the supergraph and move on.
+- **Uses `@inaccessible`, and you want codegen to catch hidden-field mistakes** →
+  feed the derived API schema (above), or introspect the live router.
+
+A large real supergraph carries more constructs than a toy one (interface
+objects via `@join__type(isInterfaceObject:)`, `@join__unionMember`, enum join
+directives). The mechanism holds, but the honest check is to run codegen against
+your actual composed schema plus a couple of representative queries before
+relying on it.

data/docs/generated_modules.md

@@ -210,9 +210,8 @@ emitted **once per schema** — one file per type under
 named from the output path: the conventional layout gets
 `GraphQLInputs`, while a multi-schema layout names each schema's module
 after its directory (`app/graphql/github/generated` → `GithubInputs`).
-Override globally with `GraphWeaver.inputs_module=` or per run with
-`generate!(inputs_module:)`; opt out with
-`generate!(shared_inputs: false)`. Per-type files keep schema drift
+Override the module name globally with `GraphWeaver.inputs_module=` or per run
+with `generate!(inputs_module:)`. Per-type files keep schema drift
 reviewable: a migration diffs exactly the types it touched, and types
 the schema drops are pruned on regeneration (`verify` flags strays).
 Query modules alias what they touch,
@@ -254,7 +253,11 @@ mod.execute!(where:)
   interface-level fields only → one shared struct; a single `... on X`
   condition and nothing else → `X`'s struct, always nilable — a
   non-matching runtime type comes back as `nil`, so narrowing doubles as
-  filtering.
+  filtering. When a whole union field is selected as one named *shared*
+  fragment (`{ ...FeedItemFields }`), that type is hoisted once into the
+  `GraphQLUnions` module and each query aliases it — so the same union is one
+  Ruby type family across queries, not a fresh dispatch module per query. Like
+  shared inputs, it's a `generate!`-directory concern; dynamic `parse` inlines.
 - **`@skip` / `@include`** — a directive-conditional field may be absent from
   the response regardless of schema nullability, so its generated type is
   always nilable.

data/docs/getting_started.md

@@ -86,6 +86,51 @@ reviewed like any other code — and never edited by hand.
 PersonQuery.execute!(id: "1").person&.name   # typed, via GraphWeaver.client
 ```
 
+### Shared fragments
+
+Define reusable fragments once and spread them from any query:
+
+```graphql
+# app/graphql/fragments/person_fields.graphql
+fragment PersonFields on Person { name birthday }
+
+# app/graphql/queries/person.graphql
+query($id: ID!) { person(id: $id) { ...PersonFields } }
+```
+
+Each query inlines only the fragments it (transitively) spreads, so the sent
+`QUERY` stays self-contained — the server never needs your fragment library.
+Fragment files hold only fragments (no operations), and names are unique across
+them. Point elsewhere with `GraphWeaver.fragments_paths` (an appendable list,
+default `app/graphql/fragments`).
+
+### Shared unions
+
+When a shared fragment *is* the whole selection on a union field, its type is
+hoisted once into a `GraphQLUnions` module and every query that spreads it
+aliases the same type — so a `union` selected across many queries becomes one
+Ruby type family, and you write one exhaustive `case … when … T.absurd` that
+works everywhere:
+
+```graphql
+# app/graphql/fragments/feed_item.graphql
+fragment FeedItemFields on FeedItem {
+  __typename
+  ... on Post { title }
+  ... on Photo { url }
+}
+
+# any query
+query { feed { ...FeedItemFields } }   # feed : T::Array[FeedItemFields::Type]
+```
+
+Hoisting is what the shared fragment buys you — there's no flag. It triggers
+only when the union field's selection is exactly that one spread (mix in other
+fields, or shadow the fragment with a query-local one of the same name, and the
+union stays inlined in that query). Named like the inputs module from the output
+path (`GraphQLUnions`, or `GithubUnions` in a multi-schema layout); override
+with `GraphWeaver.unions_module=`.
+
 ## 6. Test against fakes
 
 ```ruby
@@ -127,6 +172,13 @@ generated files — dynamic `parse` is invisible to `srb tc`. Everything
 works without Sorbet; codegen plus Sorbet is what moves type errors from
 runtime to CI.
 
+If your app globally injects `T::Sig` (`class Module; include T::Sig`), the
+per-struct `extend T::Sig` in generated files is redundant — rubocop's
+`Sorbet/RedundantExtendTSig` flags it. GraphWeaver auto-detects that at
+generation time and skips the `extend`; override with
+`GraphWeaver.extend_t_sig = true`/`false`. (Generated code is machine-generated
+and marked "do not edit," so excluding `generated/**` from rubocop is also fine.)
+
 ## Not Rails?
 
 Everything above works the same, minus the Railtie conveniences: add

data/docs/scalars.md

@@ -14,6 +14,19 @@ them: `client.register_scalar(...)` overlays the global registry for that
 client's generation only — so two servers can disagree about what a
 `DateTime` is, and neither leaks into the other.
 
+Pass a `Type.field` **coordinate** instead of a scalar name to override just
+that one field — so the same scalar can deserialize as different Ruby types
+across fields:
+
+```ruby
+GraphWeaver.register_scalar("ISO8601DateTime", Time)   # the default, everywhere
+GraphWeaver.register_scalar("User.birthday", Date)     # this field only
+```
+
+A field override wins over the scalar-name registration; both stack the same
+global-then-client way. (GraphQL names can't contain `.`, so the coordinate is
+unambiguous — and it's validated against the schema, so a typo'd field raises.)
+
 Pass a real class as `type:` and the cast/serialize are **inferred** from it by
 probing the deserialize side and pairing its serializer:
 
@@ -155,7 +168,7 @@ module PetHelpers
   def display_name = adult? ? "#{name} 🦴" : "#{name} 🐶"
 end
 
-GraphWeaver.register_type("Pet", PetHelpers)   # or api.register_type(...)
+GraphWeaver.extend_type("Pet", PetHelpers)   # or api.extend_type(...)
 
 pet.display_name   # => "Shelby 🦴"
 pet.name           # => "Shelby" — the wire value stays honest
@@ -173,7 +186,7 @@ For quick decoration, build the mixin inline — the block is
 `GraphWeaver::TypeHelpers` so generated files can reference it:
 
 ```ruby
-api.register_type("Pet") do
+api.extend_type("Pet") do
   def display_name = "#{name} 🐶"
 end
 ```

data/lib/graph_weaver/client.rb

@@ -76,7 +76,8 @@ class GraphWeaver::Client
 
   # Client-scoped scalar registration: consulted before the global
   # registry when this client generates code, so two clients can map the
-  # same scalar name onto different Ruby types. Same signature as
+  # same scalar name onto different Ruby types. A `Type.field` coordinate
+  # (e.g. "User.birthday") overrides just that field. Same signature as
   # GraphWeaver.register_scalar.
   def register_scalar(graphql_name, type, cast: nil, serialize: nil, requires: nil, coerce: nil)
     validate_registration!("scalar", graphql_name.to_s)
@@ -101,8 +102,8 @@ class GraphWeaver::Client
   # Client-scoped type helpers: include app-owned modules into every
   # struct this client generates from the named GraphQL type — pass
   # modules, or a block to build one inline. Additive with global
-  # registrations (see GraphWeaver.register_type).
-  def register_type(graphql_name, *mixins, requires: nil, &block)
+  # registrations (see GraphWeaver.extend_type).
+  def extend_type(graphql_name, *mixins, requires: nil, &block)
     validate_registration!("type", graphql_name.to_s)
     entry = @types[graphql_name.to_s] ||= { mixins: [], requires: [] }
     GraphWeaver::Codegen.add_type_helpers(entry, graphql_name, mixins, requires, block)

data/lib/graph_weaver/codegen/emit.rb

@@ -115,10 +115,10 @@ class GraphWeaver::Codegen
         names.uniq
       end
 
-      def emit_shared_aliases(out, names)
+      def emit_shared_aliases(out, names, namespace = @inputs_namespace)
         return if names.empty?
 
-        names.each { |name| out << "  #{name} = #{@inputs_namespace}::#{name}" }
+        names.each { |name| out << "  #{name} = #{namespace}::#{name}" }
         out << ""
       end
 
@@ -175,6 +175,35 @@ class GraphWeaver::Codegen
         files
       end
 
+      # The shared unions artifact as a single file: every hoisted union as a
+      # <module_name>::<Name> module. Unions don't cross-reference (each is a
+      # self-contained fragment), so there's no need for per-type files or the
+      # forward declarations recursive input types require.
+      def emit_unions_file(unions)
+        out = []
+        out << "# typed: strict"
+        out << "# frozen_string_literal: true"
+        out << ""
+        out << "# Generated by GraphWeaver — do not edit. Shared union types for this"
+        out << "# schema (named fragments on union fields); query modules alias what they use."
+        out << ""
+        requires = @requires.uniq.sort
+        if requires.any?
+          requires.each { |req| out << "require #{req.inspect}" }
+          out << ""
+        end
+        out << "module #{@module_name}"
+        out << "  extend T::Sig" << "" if GraphWeaver.extend_t_sig?
+        unions.each do |union|
+          emit_union(union, out, 1)
+          out << ""
+        end
+        out.pop if out.last == ""
+        out << "end"
+
+        { "unions.rb" => out.join("\n") + "\n" }
+      end
+
       # one type per file, wrapped in the namespace so bare sibling
       # references resolve lexically
       def inputs_file(files, name)
@@ -200,6 +229,9 @@ class GraphWeaver::Codegen
     def emit_module(root, variables)
       flatten = flatten_input(variables)
       aliases = @inputs_namespace ? shared_alias_names(variables, flatten) : []
+      # hoisted unions the result tree references, aliased so <Name>::Type and
+      # <Name>.from_h resolve to the shared module
+      union_aliases = @used_unions.map { |name| camelize(name) }.uniq.sort
 
       out = []
       out << "# typed: strict"
@@ -218,9 +250,12 @@ class GraphWeaver::Codegen
         out << "require_relative \"inputs\""
         out << ""
       end
+      if union_aliases.any?
+        out << "require_relative \"unions\""
+        out << ""
+      end
       out << "module #{@module_name}"
-      out << "  extend T::Sig"
-      out << ""
+      out << "  extend T::Sig" << "" if GraphWeaver.extend_t_sig?
       # a GraphQL block string could contain a bare GRAPHQL line, which
       # would terminate the heredoc early — pick a delimiter the query
       # can't collide with
@@ -235,6 +270,7 @@ class GraphWeaver::Codegen
       else
         emit_variable_types(out)
       end
+      emit_shared_aliases(out, union_aliases, @unions_namespace)
       emit_nested(root, out, 1)
       out << ""
       emit_execute(out, variables, flatten:)
@@ -282,14 +318,16 @@ class GraphWeaver::Codegen
       pad = "  " * indent
 
       out << "#{pad}class #{node.class_name} < T::Struct"
-      out << "#{pad}  extend T::Sig"
+      out << "#{pad}  extend T::Sig" if GraphWeaver.extend_t_sig?
       out << "#{pad}  include GraphWeaver::Hints"
       node.mixins.each do |mixin|
         out << "#{pad}  include #{mixin} # registered for #{node.graphql_type}"
       end
       out << ""
 
-      node.fields.filter_map { |field| field.node.nested }.each do |child|
+      # uniq by object identity: deduped sibling unions share one node, so the
+      # shared type is emitted once (both fields' consts already reference it).
+      node.fields.filter_map { |field| field.node.nested }.uniq.each do |child|
         emit_nested(child, out, indent + 1)
         out << ""
       end
@@ -318,8 +356,7 @@ class GraphWeaver::Codegen
       pad = "  " * indent
 
       out << "#{pad}module #{node.class_name}"
-      out << "#{pad}  extend T::Sig"
-      out << ""
+      out << "#{pad}  extend T::Sig" << "" if GraphWeaver.extend_t_sig?
 
       node.members.each_value do |member|
         emit_object(member, out, indent + 1)
@@ -346,8 +383,7 @@ class GraphWeaver::Codegen
       out << "  @client = T.let(nil, T.untyped)"
       out << ""
       out << "  class << self"
-      out << "    extend T::Sig"
-      out << ""
+      out << "    extend T::Sig" << "" if GraphWeaver.extend_t_sig?
       out << "    sig { params(client: T.untyped).void }"
       out << "    attr_writer :client"
       out << ""