graph_weaver 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f5ca284d12ebab15746910afb16a7349344b21fae0f93ad77882a3d256d4a75
-  data.tar.gz: 76e19939e81d70da81aa93da515168cdf670b65fca6d36d0412d6104589cf83d
+  metadata.gz: ef7de8e2cd115b4c757a3dac2e8c41a0e87865914e246131c1037a231f7a60af
+  data.tar.gz: fa89ee78a04a2a07b7c173c82685490ca501a2a29045ef487aae3dd6f3d915d8
 SHA512:
-  metadata.gz: b1404192f58233afd6074365e006b355cca9d9d5aefb554fd318d76430cea089e36311d69a8941e8120e4e07e6333b597ae0bf09fdb4737823ae22b4bb4ad878
-  data.tar.gz: d02a7b9e61dad2c234a4a89ac9761d493781f49eb730516d09a328dc28d3e276f4f4d68c9cbf97d468d8cec1bfddd718f0d7fce61614fd4cbd1f4dee210745be
+  metadata.gz: 4ae73ed74389baa1f08a42e38b7bf2b0bca2f95ccbe247ccb68fda733c9fee849aed3d17dbba424bdb13104344771d9789401710a5add195c71873edc379530b
+  data.tar.gz: 24e15e7a6213c0cd5dee16aa73e675649748b84993be11387f638aeca21c15db77a59b1fa5a85ae406af7182be0f9f6a17164b842add3627a7547ab1670616d1

data/.yardopts

@@ -0,0 +1,6 @@
+--markup markdown
+--title GraphWeaver
+-
+docs/*.md
+CHANGELOG.md
+LICENSE

data/CHANGELOG.md

@@ -1,3 +1,216 @@
+###  v0.2.0  (2026-07-12)
+- Cleanup pass (staff-engineer review): scalar registrations get the
+  same typo validation as enums/types; cassette replay stops recomputing
+  its key per entry; dependency-order DFS uses hash bookkeeping (big
+  bool_exp graphs); require/vocabulary residue swept; the vestigial
+  graph_weaver/testing/rspec shim removed
+- BREAKING: "client" replaces "executor" across the whole surface.
+  Generated modules: the per-call override is an optional POSITIONAL
+  first argument — PersonQuery.execute(github, id: "1") — so variables
+  own the entire kwarg namespace and NOTHING is reserved (a $client or
+  $executor variable is fine; only Ruby keywords refuse); per-module is
+  MyQuery.client=, the baked param is client:. GraphWeaver.executor= is
+  gone — GraphWeaver.client= is the one ambient slot (auto_fake swaps
+  it per example; explicit clients are self-contained and never see it).
+  Client#executor is now Client#transport (transport: to bring your
+  own); SchemaLoader.introspect/stale? speak transport. Renames:
+  FakeExecutor => Testing::FakeClient, SequenceExecutor =>
+  Testing::Sequence, RetryExecutor => GraphWeaver::Retry,
+  Recording/ReplayExecutor => Recorder/Replayer, Cassette.use(client:)
+- Live federation integration: two Ruby subgraphs (apollo-federation
+  gem) composed and routed by a real Apollo gateway (node harness under
+  spec/support/federation), with GraphWeaver introspecting through the
+  router and executing a query stitched across BOTH subgraphs — part of
+  make integration. Complements the existing supergraph-SDL codegen spec
+- graphql-over-http: a non-2xx response carrying a GraphQL errors body
+  (Apollo Server/Router send request errors as 4xx JSON) flows into the
+  Response envelope so QueryError sees the structured errors; only
+  non-GraphQL bodies (proxy pages) raise ServerError
+- Fix: input-struct serialize used bare locals (result/value) that a
+  same-named prop silently shadowed — a field named "result" dropped
+  its value onto the wrong target; generated locals now wear the
+  reserved __gw prefix (GraphQL reserves __-names, so no collision is
+  possible)
+- Input fields and variables whose Ruby name would be a keyword
+  (nil/def/end/...), a generated method (serialize/to_h), or the
+  reserved executor kwarg now refuse at generation with a pointed
+  error instead of emitting broken code
+- Non-JSON 200 bodies (proxy error pages) classify as ServerError, and
+  unserializable variables (NaN/Infinity) raise GraphWeaver::Error —
+  raw JSON::* errors no longer escape the umbrella
+- Transports redact on inspect/to_s (class + url only) — Authorization
+  headers can't leak through logs or exception dumps
+- Narrowed `... on X` selections require at least one unconditional
+  field: with every field behind @skip/@include, a matching response is
+  {} — byte-identical to a non-match — so generation refuses rather
+  than silently dropping real matches to nil
+- Integration spec against Hasura's PokeAPI: snake_case codegen,
+  recursive bool_exp variable filtering, untyped jsonb pass-through
+  (make integration)
+- BREAKING: ValidationError now descends from GraphWeaver::Error (was
+  ArgumentError) — one `rescue GraphWeaver::Error` catches everything
+- Input-struct .coerce raises on unknown hash keys with a spellchecked
+  hint — a typo'd filter key no longer silently drops off the wire
+- Client registrations (register_type/register_enum) validate at the
+  call site when the schema is already loaded; lazy clients still
+  validate at generation
+- Unregistered custom scalars emit bare T.untyped (not
+  T.nilable(T.untyped), an srb tc error under typed: strict)
+- Wire log lines carry [req N OperationName] tags; long queries
+  (introspection) truncate at debug
+- Logging: GraphWeaver.logger (any stdlib-compatible Logger; Rails.logger
+  auto-wired by the railtie) — wire traffic + timings at debug,
+  introspection/cache/codegen at info, every raised error at warn
+- Recursive input types generate — self- and mutually-referential inputs
+  (Hasura's bool_exp filter surface) emit dependency-ordered structs with
+  runtime forward declarations for cycles, so variable-driven Hasura
+  filtering works; previously raised "recursive input type"
+- Fix: snake_case GraphQL type names (Hasura, PostGraphile) camelize
+  into valid Ruby constants — pokemon_v2_pokemon => PokemonV2Pokemon
+  (previously generated a SyntaxError); wire names (__typename dispatch,
+  registry keys) are untouched
+- Everything raised is rescuable: unparseable queries wrap as
+  ValidationError (GraphQL::ParseError no longer leaks), and internal
+  NotImplementedError raises (recursive inputs, unsupported kinds,
+  subscriptions) became GraphWeaver::Error
+- Transport::HTTP takes open_timeout:/read_timeout: (defaults 10s/30s);
+  timeouts surface as retriable TransportError
+- Transport::HTTP reuses its connection (keep-alive, mutex-serialized,
+  keep_alive_timeout: for the idle window); any failure drops the socket
+  so the next call starts fresh
+- GraphQLError#code also reads a top-level "type" (GitHub's dialect:
+  NOT_FOUND, FORBIDDEN) when extensions.code is absent
+- Typo'd client-scoped registrations raise at generation with a
+  spellchecked hint (register_type("Pett") => "did you mean 'Pet'?")
+  instead of silently no-oping
+- Abstract selections narrow: __typename is only required when the
+  selection varies by concrete type. Interface-level-fields-only
+  selections generate one shared struct (no dispatch); a single
+  `... on X` condition generates X's struct, always nilable — a
+  non-matching runtime type casts to nil, so narrowing doubles as
+  filtering
+- Zero-config rspec: require "graph_weaver/rspec" now defaults
+  auto_fake on and auto-locates the schema from the committed dump
+  (config.schema= / config.auto_fake = false to override) — one line is
+  the whole test setup in a conventional app
+- examples/: runnable demos, all directly executable — countries.rb
+  (public API, no auth, all dynamic), rick_and_morty.rb (filtered
+  search, pagination, a block-built type helper), and github/ (auth,
+  checked-in generated modules; stars the repo ⭐ then tours the
+  stargazers, their top repos, and what else they've starred); excluded
+  from the gem package
+- Fix: requires: now load before codec probing, so inference sees
+  methods the required file provides — register_scalar("DateTime", Time,
+  requires: "time") correctly infers Time.parse in a fresh process
+  (previously the cast was silently skipped unless "time" was already
+  loaded)
+- docs/quickstart.md renamed to docs/getting_started.md
+- Rails Railtie: the graph_weaver:* rake tasks self-register (no
+  Rakefile edit) and depend on :environment, and generated modules load
+  at boot (after initializers) when generated_path exists; outside
+  Rails, require "graph_weaver/tasks" and call load_generated! as before
+- BREAKING (vs 0.1.0): reset_scalars! lost its coerce: flavor —
+  GraphWeaver.auto_coerce = true is the one way to default-coerce
+  (broader: convertible built-ins AND full cast/serialize scalars,
+  resolved lazily, per-registration coerce: still wins)
+- GraphWeaver.client= — the blessed global wiring: assign the app's
+  default client and generated modules resolve through it (per call ->
+  per module -> baked -> executor= -> client). executor= stays as the
+  low-level override, so test fakes still win
+- Enum mappings: register_enum("Species", PetKind) (+ bulk
+  register_enums, client-scoped variants) — generated code speaks YOUR
+  T::Enum, with the wire mapping inferred by name, pinned via map:,
+  exhaustiveness-checked at generation (fails naming gaps), and
+  fallback: to absorb unknown wire values on cast (inputs stay strict);
+  translation tables emitted into the source (X_FROM_WIRE / X_TO_WIRE)
+- Type helpers: register_type("Pet", PetHelpers) (global or
+  client-scoped, additive) — app-owned modules included into every
+  struct generated from that GraphQL type, so derived values live as
+  methods beside the honest wire data and srb tc checks them against
+  each query's selection. Or build the mixin inline with a block
+  (module_eval'd into an auto-named GraphWeaver::TypeHelpers constant —
+  quick decoration, invisible to srb tc)
+- BREAKING (vs 0.1.0): register_scalar takes the type positionally —
+  register_scalar("Money", Money, requires: ...) — matching the new
+  registrars: the GraphQL name + your Ruby type up front, options as
+  kwargs
+- GraphWeaver::Client — transport, schema, and scalars for one server in
+  one object: GraphWeaver.new(url_or_schema) takes a url (transport
+  built, schema introspected lazily per cache:/ttl:) or a schema source
+  (live class — also the in-process executor — or a path/SDL/dump);
+  #parse and #execute/#execute! bind the implicit schema + transport;
+  #register_scalar scopes scalar mappings to the client (overlaying the
+  global registry), so two servers can disagree about a scalar type
+- BREAKING: GraphWeaver.connect removed — GraphWeaver.new(url) replaces
+  it (wire generated modules with GraphWeaver.executor = client.executor)
+- BREAKING: the one-shots are now GraphWeaver.execute(url_or_schema,
+  query, **variables) / execute! — Client#execute on a throwaway client;
+  variables are plain kwargs, as on a generated module
+- Client#load_queries! — parse every query file into modules named like
+  generation would name them (reloadable; namespace: to scope): the
+  no-build-step analog of generate! + load_generated!
+- Introspected schema dumps record provenance (source url + timestamp):
+  a parsable SDL header comment, a "graph_weaver" sibling key in JSON —
+  read it back with SchemaLoader.provenance(path), check drift with
+  SchemaLoader.stale?(path) or rake graph_weaver:schema:verify, rewrite
+  with rake graph_weaver:schema:refresh (GRAPHWEAVER_AUTH for tokens)
+- generate!/verify_generated!/rake auto-locate the schema dump at
+  schema_path in any supported format; SchemaLoader.locate is public
+- Calling a result field by its camelCase wire name raises a pointed
+  NoMethodError naming the snake_case prop that does exist
+  (result.addPet => "use 'add_pet'"), and near-miss typos in either
+  casing get a spellchecked suggestion (result.addPt => "did you mean
+  'add_pet'?") — the runtime companion to srb tc's static flag
+- BREAKING: an operation whose only variable is a required input object
+  (the Relay convention) now flattens the input's fields into execute's
+  kwargs — AdoptQuery.execute!(name:, species:) instead of
+  execute!(input: {...}); multi-variable / nullable-input operations
+  keep the input: kwarg (struct or hash)
+- Enum kwargs accept the T::Enum or its wire value (T.any(Enum, String))
+  everywhere — variables now match input-hash fields
+- BREAKING: HttpExecutor / FaradayExecutor are now Transport::HTTP /
+  Transport::Faraday, subclasses of the new abstract GraphWeaver::Transport
+  base, which owns the shared flow (encode, TransportError reclassify,
+  non-2xx ServerError, parse) — a custom transport just implements
+  post(body) => [status, body]. Opt-in require moved:
+  "graph_weaver/faraday_executor" -> "graph_weaver/transport/faraday"
+- SchemaLoader.introspect cache: reuses a fresh dump in ANY supported
+  format before re-introspecting (an existing schema.graphql wins over
+  writing schema.json), and accepts :json / :graphql / :gql to pick the
+  format at GraphWeaver.schema_path's location
+- rubydoc.info rendering: ship .yardopts (markdown markup, docs/ guides
+  as extra files) and re-indent docstring examples so code blocks and
+  backticks render; make docs previews locally
+- GraphWeaver.connect(url, auth:, headers:, retries:): one-shot setup —
+  best transport (Faraday when the app loads it; detection is defined?,
+  never a require), bearer/verbatim auth, opt-in RetryExecutor wrapping
+  (true / options Hash; off by default), wired in as the global executor
+- Generation workflow: GraphWeaver.generate! (queries dir -> generated
+  dir), verify_generated! (the freshness guard — raises naming stale
+  files), load_generated! (factory_bot-style explicit loading), rake
+  tasks (require "graph_weaver/tasks": graph_weaver:generate / :verify),
+  all defaulting to configurable conventional paths (queries_path /
+  generated_path / schema_path)
+- GraphWeaver.auto_coerce = true: default input coercion for scalars
+  without an explicit coerce:, resolved lazily at generation time (no
+  reset_scalars! ordering dance) — convertible built-ins take their
+  conversion, cast/serialize pairs take parse-style coercion
+- SchemaLoader.introspect cache: true — caches at GraphWeaver.schema_path,
+  in the format the extension picks: .json (verbatim wire artifact) or
+  .graphql/.gql (SDL — human-readable, PR-reviewable diffs);
+  the same dump rake graph_weaver:generate reads
+- docs/transports.md: connect, the executor contract, Faraday, retries
+- Cassette workflow: GRAPHWEAVER_RECORD=1 / config.record force
+  re-recording; config.anonymize scrubs responses as they are recorded
+  (caller sees the anonymized data too, so assertions hold on replay);
+  rake graph_weaver:cassettes:anonymize; docs/cassettes.md guide
+- auto_coerce reaches input-object fields: raw scalar values inside
+  input hashes coerce via the registry, mutations included
+- RetryExecutor: composable retries over any transport — tries:,
+  exponential/linear/custom backoff with jitter and max clamp,
+  retry-by-error-class (5xx yes, 4xx no by default; retry_if: override)
+  and retry-by-GraphQL-code (retry_codes: ["THROTTLED"])
+
 ###  v0.1.0  (2026-07-11)
 - Structured errors: execute returns a typed Response envelope (#data/#data!,
   #errors, #errors?, #extensions) instead of raising on GraphQL errors, so

data/Gemfile.lock

@@ -1,13 +1,16 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.1.0)
+    graph_weaver (0.2.0)
       graphql (>= 2)
       sorbet-runtime
 
 GEM
   remote: https://rubygems.org/
   specs:
+    apollo-federation (3.10.3)
+      google-protobuf (< 5)
+      graphql
     base64 (0.3.0)
     benchmark (0.5.0)
     bigdecimal (4.1.2)
@@ -28,6 +31,18 @@ GEM
     faraday-net_http (3.4.4)
       net-http (~> 0.5)
     fiber-storage (1.0.1)
+    google-protobuf (4.35.1-aarch64-linux-gnu)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.35.1-arm64-darwin)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.35.1-x86_64-darwin)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.35.1-x86_64-linux-gnu)
+      bigdecimal
+      rake (~> 13.3)
     graphql (2.6.5)
       base64
       fiber-storage
@@ -50,6 +65,7 @@ GEM
       prettyprint
     prettyprint (0.2.0)
     prism (1.9.0)
+    rake (13.4.2)
     rbi (0.3.14)
       prism (~> 1.0)
       rbs (>= 4.0.1)
@@ -62,6 +78,7 @@ GEM
       prism (>= 1.6.0)
       rbs (>= 4.0.0)
       tsort
+    redcarpet (3.6.1)
     reline (0.6.3)
       io-console (~> 0.5)
     require-hooks (0.4.0)
@@ -122,6 +139,7 @@ GEM
     tsort (0.2.0)
     uri (1.1.1)
     webrick (1.9.2)
+    yard (0.9.44)
 
 PLATFORMS
   aarch64-linux
@@ -131,18 +149,23 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  apollo-federation
   bigdecimal
   debug
   faker
   faraday
   graph_weaver!
+  rake
+  redcarpet
   rspec
   simplecov
   sorbet
   tapioca
   webrick
+  yard
 
 CHECKSUMS
+  apollo-federation (3.10.3) sha256=61e6d8e1fd695ee45bab5d84f86f586d99c296ad77a86c6f1e7b964ac17be3d7
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
   benchmark (0.5.0) sha256=465df122341aedcb81a2a24b4d3bd19b6c67c1530713fd533f3ff034e419236c
   bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
@@ -156,7 +179,11 @@ CHECKSUMS
   faraday (2.14.3) sha256=1882247e6766615c8220b4392bf1d27f6ebb63d8e28267587cef1fb0bf37f278
   faraday-net_http (3.4.4) sha256=0e78af151747ed1b00f33e25973b4bc220d7f16c00c39676817c8b12331eb588
   fiber-storage (1.0.1) sha256=f48e5b6d8b0be96dac486332b55cee82240057065dc761c1ea692b2e719240e1
-  graph_weaver (0.1.0)
+  google-protobuf (4.35.1-aarch64-linux-gnu) sha256=50ca44d0eeff3f8475e630a1accdd974256f3510694d574e2c9d6119ea8bc9e1
+  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.0)
   graphql (2.6.5) sha256=1051825bfb4aedb4293cdbcd9726c3150e69e3512556609a32c2ca19d4be3d00
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
@@ -169,9 +196,11 @@ CHECKSUMS
   pp (0.6.4) sha256=dfcb0fce700c41456265922884f9fe195d7fbb0674a3578e6c0f69588e82b570
   prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
   rbi (0.3.14) sha256=932ed904adbb5ca645c285c8b36da1b7ff6321ec1870d187d6325248cb637658
   rbs (4.0.3) sha256=5a7bf70e2628549d9a1f44eae447b2cfe55968a9c60cfff52693a4bdcc020e14
   rdoc (8.0.0) sha256=03bf8c08a9639658855a0cfd77c0abca8325c227693f7f33f82957811348c469
+  redcarpet (3.6.1) sha256=d444910e6aa55480c6bcdc0cdb057626e8a32c054c29e793fa642ba2f155f445
   reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
   require-hooks (0.4.0) sha256=005f4c6435b4edae73e358cdbaba48370a4121f9ce893d5d2a3c66fce855677d
   rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
@@ -199,6 +228,7 @@ CHECKSUMS
   tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
   uri (1.1.1) sha256=379fa58d27ffb1387eaada68c749d1426738bd0f654d812fcc07e7568f5c57c6
   webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131
+  yard (0.9.44) sha256=eb087e9b631ccd887b049f303d489963945452d5e2a7eb49a5a74a7cf6887f28
 
 BUNDLED WITH
   4.0.10

data/Makefile

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

data/NOTES.md

@@ -25,7 +25,7 @@ order, each backed by a spec.
 
 The specs are the documentation — each one asserts an observed behavior:
 
-```
+```sh
 bundle exec rspec
 ```
 

data/PLAN.md

@@ -26,7 +26,7 @@ requires:, opt-in input coercion incl. built-ins).
 Sources: live schema / introspection JSON / SDL — byte-identical output
 (enum values + abstract-type members sorted for determinism).
 Transport: executor precedence per call → per module → baked const →
-GraphWeaver.executor; HttpExecutor (zero-dep) + opt-in FaradayExecutor
+GraphWeaver.executor; Transport::HTTP (zero-dep) + opt-in Transport::Faraday
 (url / block middleware / ready connection), e2e specs against WEBrick.
 Errors: typed Response envelope (partial data + extensions survive) and
 a GraphWeaver::Error hierarchy (Transport/Server/Query/Validation/Type)
@@ -102,3 +102,36 @@ Response envelope; execute! for raise-or-result).
   resolvers — codegen must stay name-keyed, never call schema runtime hooks
 - graphql-client (the gem) casts scalars via coerce_isolated_input and
   only with a live schema class — documented in the early specs
+
+## From the field-test experiments (2026-07-12)
+
+A junior + senior agent pair exercised the repo cold (clone, examples,
+extensions, a Pokedex app against Hasura's 4,441-type PokeAPI schema).
+Fixed same-day: snake_case type names generated invalid constants
+(camelize), GraphQL::ParseError/NotImplementedError escaping the Error
+umbrella, HttpExecutor timeouts, GitHub's top-level "type" error codes,
+typo'd client registrations silently no-oping. Still open:
+
+~~Recursive input types~~ DONE 2026-07-12: register-before-walk breaks
+the recursion; emission dependency-orders the structs and, for cycles,
+forward-declares the classes in an eval (srb rejects reopening a
+T::Struct statically, but adding props at runtime works — the full
+bodies below the eval are all srb sees). Verified live against Hasura
+bool_exp.
+
+~~Connection reuse in Transport::HTTP~~ DONE 2026-07-12: persistent
+keep-alive connection behind a mutex, dropped on any failure; net/http's
+keep_alive_timeout handles idle expiry. Faraday remains the pooling
+answer.
+
+- Subscriptions; @defer/@stream (routers send multipart responses — the
+  transport classifies them as ServerError today, no incremental support).
+- Shared input-type structs across generated modules: one Hasura
+  bool_exp variable pulls its whole recursive closure into EVERY module
+  (~28k lines each) — correct but heavy in PRs; needs cross-module
+  sharing or selection-based pruning (field-test round 2).
+- Structured logging: log_tag pairs lines and names operations now, but
+  events are prose — an optional {event:, url:, ms:} payload contract, a
+  scrub_variables hook, and cache-age on hit lines (field-test round 2).
+- Cut 0.1.1 — RubyGems 0.1.0 is materially behind main (snake_case fix,
+  recursive inputs, keep-alive, logging, error umbrella).

data/README.md

@@ -26,85 +26,105 @@ result.person&.birthday   # => Date (custom scalars deserialize)
 result.person&.nmae       # => srb tc: Method `nmae` does not exist
 ```
 
+New here? The **[getting started](docs/getting_started.md)** guide walks the
+production setup end to end — initializer, codegen, fakes, CI. Or run the
+**[examples](examples/)**, smallest first: `examples/countries.rb` (public
+API, no auth, all dynamic), `examples/rick_and_morty.rb` (filtering,
+pagination, a block-built type helper), and `examples/github/run.rb`
+(auth + checked-in generated modules; it stars this repo ⭐ and introduces
+you to your fellow stargazers).
+
 #### Features
 
 - **Queries and mutations** with typed variable kwargs — enums as `T::Enum`s, input objects as `T::Struct`s, required vs optional falling out of nullability and defaults
 - **Fragments** (inline, named, type conditions), **unions and interfaces** (member structs, `__typename` dispatch), **custom scalars** (pluggable registry), `@skip`/`@include` nullability
 - **Any schema source**: live schema class, introspection JSON, or SDL — including Apollo Federation supergraph SDL; introspect live endpoints with caching
-- **Any transport**: in-process schema execution, the zero-dependency HTTP executor, or Faraday with your own middleware — swap per call with `executor:`
+- **Any transport**: in-process schema execution, the zero-dependency HTTP executor, or Faraday with your own middleware — plus a composable `Retry` (exponential/linear/custom backoff, jitter, retry-by-error-class or GraphQL code) — swap per call with `executor:`
 - **Structured errors**: a typed response envelope (partial data + extensions survive), an error hierarchy split by failure site, field-level reports with entity ids, and `schema_stale?` detection — every error dual-surfaced as a human message plus JSON-ready `#to_h`
 - **Testing built in**: schema-correct fakes, failure simulation, record/replay cassettes with anonymization, rspec integration
 - **Dynamic mode** for development: `GraphWeaver.parse(...)` generates and evals on the fly, no build step
 
 #### Usage
 
+Three ways to run a query — pick by context:
+
+| Context | Use |
+|---------|-----|
+| Production | checked-in codegen (`rake graph_weaver:generate`) — reviewed, `srb tc`-checked |
+| Development, consoles | `client.parse` / `client.load_queries!` — no build step |
+| Scripts, one-offs | `client.execute!` — no module at all |
+
+The production path assembled is the [getting started](docs/getting_started.md);
+the pieces:
+
 ```ruby
 require "graph_weaver"
 
-# configure the default transport once (override per module or per call)
-GraphWeaver.executor = GraphWeaver::HttpExecutor.new("https://api.example.com/graphql")
+# a client for one server: transport (Faraday when loaded), auth, and a
+# lazily introspected schema. The first argument is a url or any schema
+# source — a live schema class, or a .json/.graphql dump
+api = GraphWeaver.new("https://api.example.com/graphql", auth: ENV["API_TOKEN"], cache: true)
 
-# generate from any schema source
-schema = GraphWeaver::SchemaLoader.load("schema.json")   # or .graphql SDL, or a live class
+# make it the app default — generated modules execute through it
+GraphWeaver.client = api
 
+# generate checked-in typed modules (rake graph_weaver:generate, or directly)
 source = GraphWeaver::Codegen.generate(
-  schema:,
+  schema: api.schema,
   query: File.read("queries/person.graphql"),
   module_name: "PersonQuery",
 )
 File.write("app/queries/person_query.rb", source)
 
 # at runtime
-PersonQuery.execute(id: "1")                        # uses GraphWeaver.executor
-PersonQuery.execute(id: "1", executor: other)       # or per call
+PersonQuery.execute(id: "1")                        # via GraphWeaver.client
+PersonQuery.execute(other_client, id: "1")          # or per call
 ```
 
 Module names derive from the operation name (`query GetPerson` →
-`GetPerson`) or, for `GraphWeaver.parse` on a `.graphql` file, from the
-file name; pass `module_name:`/`name:` to override. Pass `executor:` (a
-constant) to bake a default transport into the generated module.
+`GetPerson`) or, for `parse` on a `.graphql` file, from the file name;
+pass `module_name:`/`name:` to override. Pass `client:` (a constant) to
+bake a default client into the generated module. Prefer Faraday? It's
+opt-in (`gem "faraday"`), and the client picks it up when loaded —
+middleware blocks and ready connections in [transports](docs/transports.md).
 
-Prefer Faraday? It's opt-in (`gem "faraday"` in your Gemfile):
-
-```ruby
-require "graph_weaver/faraday_executor"
-
-# from a url, with optional middleware customization
-executor = GraphWeaver::FaradayExecutor.new("https://api.example.com/graphql") do |conn|
-  conn.request :authorization, "Bearer", -> { Tokens.fetch }
-  conn.response :logger
-end
-
-# or bring a fully configured Faraday connection
-executor = GraphWeaver::FaradayExecutor.new(MyApp.faraday_connection)
-```
-
-In development, skip the build step entirely:
+In development, skip the build step entirely — modules from `client.parse`
+carry the client's transport, no global wiring needed:
 
 ```ruby
 # parse a query into a typed module on the fly — a .graphql path or a raw string
-PersonQuery = GraphWeaver.parse(schema:, query: "queries/person.graphql")
-PeopleQuery = GraphWeaver.parse(schema:, query: "query { people { name } }")
+PersonQuery = api.parse("queries/person.graphql")
 PersonQuery.execute(id: "1")
 
-# or one-shot, no module at all
-GraphWeaver.execute(schema:, query: "query($id: ID!) { person(id: $id) { name } }", variables: { id: "1" })
+# or every query file at once (queries_path convention), named like generation would
+api.load_queries!
+
+# or one-shot, no module at all — variables are plain kwargs
+api.execute!("query($id: ID!) { person(id: $id) { name } }", id: "1")
 ```
 
 
 #### Dig deeper
 
+- **[Getting started](docs/getting_started.md)** — the production path in Rails,
+  step by step: initializer, rake tasks, fakes, CI, Sorbet or not
 - **[Generated modules](docs/generated_modules.md)** — module anatomy, typed
   variables (enums, input objects), fragments/unions/interfaces,
-  `@skip`/`@include`, naming, executors, dynamic mode
-- **[Against a real API](docs/real_world.md)** — introspect a live endpoint
-  (GitHub end to end), schema caching
+  `@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
+- **[Transports](docs/transports.md)** — clients, the execute contract,
+  Faraday, retries and backoff
 - **[Custom scalars](docs/scalars.md)** — the registry: codec inference,
   requires, input coercion
 - **[Errors](docs/errors.md)** — the Response envelope, the error hierarchy,
   field-level reports with entity ids, stale-schema detection
+- **[Logging](docs/logging.md)** — point `GraphWeaver.logger` at any Logger:
+  wire traffic at debug, introspection/cache/codegen at info, errors at warn
 - **[Testing](docs/testing.md)** — schema-correct fakes, failure simulation,
-  cassettes with anonymized capture, rspec integration
+  rspec integration
+- **[Cassettes](docs/cassettes.md)** — capture and replay real API
+  responses; anonymized recording (`GRAPHWEAVER_RECORD=1`, rake tasks)
 
 ----
 ## Installation
@@ -116,7 +136,7 @@ gem "graph_weaver"
 
 or
 
-```
+```sh
 gem install graph_weaver
 ```
 
@@ -125,8 +145,3 @@ gem install graph_weaver
 
 - `make check` — regenerate spec fixtures, run specs, typecheck
 - `make integration` — one-off checks against the live GitHub and Countries APIs
-
-See `PLAN.md` for roadmap and `NOTES.md` for the research notebook this
-gem grew out of (an exploration of graphql-client internals — GraphWeaver
-is a standalone client, not an extension; it depends only on `graphql`
-and `sorbet-runtime`).

data/docs/cassettes.md

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