graph_weaver 0.4.6 → 0.5.0

data/CLAUDE.md

@@ -8,6 +8,50 @@ 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
@@ -20,10 +64,11 @@ where it pays off in developer experience; leave the rest at `# typed: true`.
   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.**
+  `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).
@@ -48,15 +93,62 @@ where it pays off in developer experience; leave the rest at `# typed: true`.
 
 ## 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 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
 ```
 
-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
+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**:

data/DECISIONS.md

@@ -0,0 +1,309 @@
+# 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/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.4.6)
+    graph_weaver (0.5.0)
       graphql (>= 2.6.7)
       sorbet-runtime
 
@@ -42,7 +42,7 @@ GEM
     google-protobuf (4.35.1-x86_64-linux-gnu)
       bigdecimal
       rake (~> 13.3)
-    graphql (2.6.7)
+    graphql (2.6.10)
       base64
       fiber-storage
       logger
@@ -54,7 +54,7 @@ GEM
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.20.0)
+    json (2.21.2)
     logger (1.7.0)
     net-http (0.9.1)
       uri (>= 0.11.1)
@@ -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.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)
+    simplecov (1.1.1)
+    sorbet (0.6.13454)
+      sorbet-static (= 0.6.13454)
+    sorbet-runtime (0.6.13454)
+    sorbet-static (0.6.13454-aarch64-linux)
+    sorbet-static (0.6.13454-universal-darwin)
+    sorbet-static (0.6.13454-x86_64-linux)
+    sorbet-static-and-runtime (0.6.13454)
+      sorbet (= 0.6.13454)
+      sorbet-runtime (= 0.6.13454)
     spoom (1.8.3)
       erubi (>= 1.10.0)
       prism (>= 0.28.0)
@@ -176,12 +176,12 @@ 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.4.6)
-  graphql (2.6.7) sha256=759755ce5819c965b6459c5039605cf2e4d876bb8ba5e03451676870ea787c45
+  graph_weaver (0.5.0)
+  graphql (2.6.10) sha256=9b7c8633767f516ff9d48a8d6305b2a00a2101c82aa871b92e69086944f9f83e
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
   irb (1.18.0) sha256=de9454a0703a54704b9811a5ef31a60c86949fbf4013fcf244fabc7c775248e3
-  json (2.20.0) sha256=9362bc6e55a952b056abf9167cf053358181c904cb70cd6eee0808ea830fc32b
+  json (2.21.2) sha256=1f1d3b7cf2b3ba1a69beca0bb6db13d5438b80bff3cd54cdaaa620b9b07c1c6a
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   net-http (0.9.1) sha256=25ba0b67c63e89df626ed8fac771d0ad24ad151a858af2cc8e6a716ca4336996
   netrc (0.11.0) sha256=de1ce33da8c99ab1d97871726cba75151113f117146becbe45aa85cb3dabee3f
@@ -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.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
+  simplecov (1.1.1) sha256=25825ef13f0b2e74694d769817dad6ab8e90131dabdaa666e522fea105521e78
+  sorbet (0.6.13454) sha256=3273dda082b8aa5ecf79b7675e2b79127f202a45370d881124af3af19a3c2b35
+  sorbet-runtime (0.6.13454) sha256=b9441ae4bd265f51861c54240e8c5888f6355e3284885b21c5154b184e791d80
+  sorbet-static (0.6.13454-aarch64-linux) sha256=e09dd1e6cd7e63b3fb6c8c9c6785eeb55a6c4afecb0f932538ee4401b4552632
+  sorbet-static (0.6.13454-universal-darwin) sha256=6ac0cf10ae2b4e0e9ecabb886f9be739046424dc35d100e7888c8538a223f93a
+  sorbet-static (0.6.13454-x86_64-linux) sha256=569c52ea926e514ebfdc64825f65cd188b7aba5c1b480cc26e1870fd53d5e2c0
+  sorbet-static-and-runtime (0.6.13454) sha256=defc00684a6f8bd498bb70a4541f293b9232938a776137946247cba4baed3d20
   spoom (1.8.3) sha256=32871fa189bbfa49cf557a50f819f23cc9a6ceefd0346caa7a6adc193becd5dd
   tapioca (0.19.2) sha256=938731b07811aee8d23871b1aee8861d464fbaf2cfffbf79a62b0c869a5120ec
   thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73

data/NOTES.md

@@ -174,9 +174,9 @@ design:
 ## Open questions
 
 - interface-typed fields (vs fragment conditions, which work)
-- name collisions: the generator disambiguates one level (field-name
-  prefix) and raises otherwise. A real gem needs a *stable* naming scheme:
-  names shouldn't shift when unrelated selections are added (generated
-  code is checked in and referenced by app code), which argues for
-  path-based or explicitly-aliased names over first-come-first-served
+- ~~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)