graph_weaver 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df338e7f577c07e2941daf8e7a06af9a04e04ecfceae6c02a7e6d6619e219a0f
-  data.tar.gz: 939e9c9db69ed23b484ebd60401b96e5b51fea10aa6ee0b4e6c9a62118243302
+  metadata.gz: 8f5ca284d12ebab15746910afb16a7349344b21fae0f93ad77882a3d256d4a75
+  data.tar.gz: 76e19939e81d70da81aa93da515168cdf670b65fca6d36d0412d6104589cf83d
 SHA512:
-  metadata.gz: 3eaf7a927dbde9d9eac7353a8d01623a099e5904c458113274bf347524d00567a8d0fdd3794312f2931feb9f0a7fbd212eccfdfc9b09671e646cbfd1a8d35294
-  data.tar.gz: cc4ae772c0c38f3cb547d37ddc88821a1eb9172d8df42c4b0608242c0df19ca4ad669e246c72806fc53701be95fa7a4a4945723725075812ecf4ec602bcd63f0
+  metadata.gz: b1404192f58233afd6074365e006b355cca9d9d5aefb554fd318d76430cea089e36311d69a8941e8120e4e07e6333b597ae0bf09fdb4737823ae22b4bb4ad878
+  data.tar.gz: d02a7b9e61dad2c234a4a89ac9761d493781f49eb730516d09a328dc28d3e276f4f4d68c9cbf97d468d8cec1bfddd718f0d7fce61614fd4cbd1f4dee210745be

data/CHANGELOG.md

@@ -1,3 +1,69 @@
+###  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
+  partial data and top-level extensions (cost/throttle) survive. Error classes
+  under GraphWeaver::Error — TransportError (network), ServerError (non-2xx
+  HTTP, #status/#body), QueryError (#errors/#data/#extensions/#codes),
+  ValidationError (build-time) — plus a GraphQLError value object with #code.
+  Transport-error classification is an extensible Set (GraphWeaver.transport_errors
+  / register_transport_error): each transport seeds its own network exceptions
+  and apps can add more (e.g. a connection-pool timeout).
+  The envelope is a single generic GraphWeaver::Response[Result] (no per-query
+  wrapper class). execute! is the shortcut for execute(...).data! — the typed
+  result or a raised QueryError — on both generated modules and the one-shot
+  GraphWeaver.execute!/execute.
+  BREAKING: module #execute returns Response; use #execute! (or #data!) for
+  the old raise-or-result behavior. GraphWeaver.execute now returns the
+  envelope too; GraphWeaver.execute! returns the result.
+- GraphWeaver.register_scalar: custom scalar deserialization into rich Ruby
+  objects. cast/serialize inferred from a class type via paired codecs
+  (.parse/#to_s or .load/.dump), or given as a Symbol/Proc (:itself opts out);
+  requires: emits (validated, and require-checked when type: is a class)
+  requires into generated source — the built-in Date scalar carries
+  require "date" so Date-using queries are self-contained; coerce: true lets a
+  variable accept the value or its raw input (coerce: :to_f for a built-in
+  conversion), casting/converting the latter — reset_scalars!(coerce: true)
+  reloads the built-ins coercible; built-in scalars pre-registered in one
+  overridable registry (reset_scalars!/clear_scalars!)
+- FaradayExecutor: url, Faraday connection, or middleware block
+- GraphWeaver.executor default transport; per-module executor= override
+- GraphWeaver.parse and GraphWeaver.execute (dynamic queries)
+- Codegen.generate shorthand; executor: takes a constant; module_name
+  derived from operation or file name
+- Error ergonomics: schema_stale? (validation-shaped rejections hint at
+  regeneration), errors_at(path) + each_error/errors_by_field filtering,
+  #report (field-keyed rollup with entity ids resolved from partial
+  data), #to_h across the hierarchy (JSON-ready machine output), and
+  GraphWeaver::TypeError wrapping cast failures with the failing struct
+- SchemaLoader: introspect(executor, cache:, ttl:) fetches schemas from
+  live endpoints with file caching; load accepts introspection JSON /
+  SDL content / Hashes as well as paths (cache round-trips)
+- GraphWeaver::Testing (require "graph_weaver/testing", or
+  "graph_weaver/rspec" for the rspec integration): FakeExecutor
+  fabricates schema-correct castable responses (mode: :faker semantic
+  values / :literal; overrides by GraphQL name; seeded; list_size /
+  null_chance), failure simulation (Failure.transport/server/graphql/
+  throttled/stale_schema, SequenceExecutor for retries, fail_at: with
+  spec-correct null propagation, corrupt: for derived type mismatches),
+  cassette record/replay above the transport, and Cassette#anonymize!
+  (shape-preserving, consistent id mapping). rspec: seed follows
+  --seed; auto_fake installs a fake executor per example
+- one-off integration specs against live GitHub + Countries APIs
+  (make integration)
+- Input objects: INPUT_OBJECT variables generate module-level T::Structs
+  with serialize (aliased to_h) producing the wire hash; execute kwargs
+  also accept plain hashes, normalized + type-checked via the generated
+  .coerce (underscored Symbol/String keys, enums as instances or wire
+  values, nested inputs as hashes)
+- fields under @skip/@include generate nilable regardless of schema
+  nullability; FakeExecutor honors first/last/limit when sizing lists
+- eval hardening for parse: module names must be constant names, and
+  QUERY heredocs can't be terminated early by block strings
+- GraphWeaver::Selection: one shared query-walk (codegen, FakeExecutor,
+  anonymizer); codegen split into scalar_type / nodes / emit
+- docs/: generated_modules, real_world, scalars, errors, testing;
+  README slimmed to pitch + quickstart
+
 ###  v0.0.1  (2026-07-07)
 - voila: typed codegen (T::Structs, T::Enums, typed variable kwargs)
 - queries + mutations; fragments, unions, interfaces, enums, custom scalars

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.0.1)
+    graph_weaver (0.1.0)
       graphql (>= 2)
       sorbet-runtime
 
@@ -10,6 +10,8 @@ GEM
   specs:
     base64 (0.3.0)
     benchmark (0.5.0)
+    bigdecimal (4.1.2)
+    concurrent-ruby (1.3.7)
     debug (1.11.1)
       irb (~> 1.10)
       reline (>= 0.3.8)
@@ -17,18 +19,31 @@ GEM
     docile (1.4.1)
     erb (6.0.4)
     erubi (1.13.1)
+    faker (3.8.0)
+      i18n (>= 1.8.11, < 2)
+    faraday (2.14.3)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.4)
+      net-http (~> 0.5)
     fiber-storage (1.0.1)
     graphql (2.6.5)
       base64
       fiber-storage
       logger
+    i18n (1.15.2)
+      concurrent-ruby (~> 1.0)
     io-console (0.8.2)
     irb (1.18.0)
       pp (>= 0.6.0)
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
+    json (2.20.0)
     logger (1.7.0)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
     netrc (0.11.0)
     parallel (2.1.0)
     pp (0.6.4)
@@ -74,15 +89,15 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    sorbet (0.6.13323)
-      sorbet-static (= 0.6.13323)
-    sorbet-runtime (0.6.13323)
-    sorbet-static (0.6.13323-aarch64-linux)
-    sorbet-static (0.6.13323-universal-darwin)
-    sorbet-static (0.6.13323-x86_64-linux)
-    sorbet-static-and-runtime (0.6.13323)
-      sorbet (= 0.6.13323)
-      sorbet-runtime (= 0.6.13323)
+    sorbet (0.6.13327)
+      sorbet-static (= 0.6.13327)
+    sorbet-runtime (0.6.13327)
+    sorbet-static (0.6.13327-aarch64-linux)
+    sorbet-static (0.6.13327-universal-darwin)
+    sorbet-static (0.6.13327-x86_64-linux)
+    sorbet-static-and-runtime (0.6.13327)
+      sorbet (= 0.6.13327)
+      sorbet-runtime (= 0.6.13327)
     spoom (1.8.3)
       erubi (>= 1.10.0)
       prism (>= 0.28.0)
@@ -105,6 +120,7 @@ GEM
       tsort
     thor (1.5.0)
     tsort (0.2.0)
+    uri (1.1.1)
     webrick (1.9.2)
 
 PLATFORMS
@@ -115,7 +131,10 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  bigdecimal
   debug
+  faker
+  faraday
   graph_weaver!
   rspec
   simplecov
@@ -126,17 +145,25 @@ DEPENDENCIES
 CHECKSUMS
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
   benchmark (0.5.0) sha256=465df122341aedcb81a2a24b4d3bd19b6c67c1530713fd533f3ff034e419236c
+  bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
+  concurrent-ruby (1.3.7) sha256=4412caec3a5ea2e5fdc52076724c071a81f2c0593d83b2ac8cbb8ca63b3151b0
   debug (1.11.1) sha256=2e0b0ac6119f2207a6f8ac7d4a73ca8eb4e440f64da0a3136c30343146e952b6
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
   erb (6.0.4) sha256=38e3803694be357fe2bfe312487c74beaf9fb4e5beb3e22498952fe1645b95d9
   erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9
+  faker (3.8.0) sha256=c147b308df73a90f27a4fc84f18d4c22ef0ad9c2a64b2b61c86fd0ca71753efc
+  faraday (2.14.3) sha256=1882247e6766615c8220b4392bf1d27f6ebb63d8e28267587cef1fb0bf37f278
+  faraday-net_http (3.4.4) sha256=0e78af151747ed1b00f33e25973b4bc220d7f16c00c39676817c8b12331eb588
   fiber-storage (1.0.1) sha256=f48e5b6d8b0be96dac486332b55cee82240057065dc761c1ea692b2e719240e1
-  graph_weaver (0.0.1)
+  graph_weaver (0.1.0)
   graphql (2.6.5) sha256=1051825bfb4aedb4293cdbcd9726c3150e69e3512556609a32c2ca19d4be3d00
+  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
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  net-http (0.9.1) sha256=25ba0b67c63e89df626ed8fac771d0ad24ad151a858af2cc8e6a716ca4336996
   netrc (0.11.0) sha256=de1ce33da8c99ab1d97871726cba75151113f117146becbe45aa85cb3dabee3f
   parallel (2.1.0) sha256=b35258865c2e31134c5ecb708beaaf6772adf9d5efae28e93e99260877b09356
   pp (0.6.4) sha256=dfcb0fce700c41456265922884f9fe195d7fbb0674a3578e6c0f69588e82b570
@@ -160,16 +187,17 @@ CHECKSUMS
   simplecov (0.22.0) sha256=fe2622c7834ff23b98066bb0a854284b2729a569ac659f82621fc22ef36213a5
   simplecov-html (0.13.2) sha256=bd0b8e54e7c2d7685927e8d6286466359b6f16b18cb0df47b508e8d73c777246
   simplecov_json_formatter (0.1.4) sha256=529418fbe8de1713ac2b2d612aa3daa56d316975d307244399fa4838c601b428
-  sorbet (0.6.13323) sha256=78b2d4b17fe171b2facd636033ce6e0be8544aa776b7713216209ba015d911d3
-  sorbet-runtime (0.6.13323) sha256=cf9c4e6793e1a9ef69bd96e3a006e0fd1fead429f4e4370163460bf569a23518
-  sorbet-static (0.6.13323-aarch64-linux) sha256=33d428073b491970b1b2528d6a89c4f104fdaf7f8752c6489f120040faafc5c4
-  sorbet-static (0.6.13323-universal-darwin) sha256=35ea7cca7011adea28fd7aa18002aff7f242365d829ca31219ad5e723fe28270
-  sorbet-static (0.6.13323-x86_64-linux) sha256=8ce81180e0e91394a87bf39722ff797f90315d71e29559f015716b3512347373
-  sorbet-static-and-runtime (0.6.13323) sha256=04b636933a28c8adedc81ad469f25d3a59b8a3eceaeef9accd6a92e2066d461d
+  sorbet (0.6.13327) sha256=4b56cb04542661c6bf5075f1ca38ca00506045325fd689f460aee8466dd3d7a3
+  sorbet-runtime (0.6.13327) sha256=86f32b2df6d266bf5c0e0eb8ea81d0376ba36eece4c8610938174e403222948d
+  sorbet-static (0.6.13327-aarch64-linux) sha256=da8a575785d34641095631c50fe1d1f645ee8782c8e2aa5a0ecfd12d1fa22a8a
+  sorbet-static (0.6.13327-universal-darwin) sha256=a2a8c6b624aada3f6ef68852398de756248f71b3ea691119873515847010dcda
+  sorbet-static (0.6.13327-x86_64-linux) sha256=f3a915bab4af1979145c793a08d3b1db207526d5e2f332513da10a95e70f9028
+  sorbet-static-and-runtime (0.6.13327) sha256=7b039be023b6a7d2d17b1f751191f32307d9ace4170b6a192bb0e005d222e00e
   spoom (1.8.3) sha256=32871fa189bbfa49cf557a50f819f23cc9a6ceefd0346caa7a6adc193becd5dd
   tapioca (0.19.2) sha256=938731b07811aee8d23871b1aee8861d464fbaf2cfffbf79a62b0c869a5120ec
   thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73
   tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+  uri (1.1.1) sha256=379fa58d27ffb1387eaada68c749d1426738bd0f654d812fcc07e7568f5c57c6
   webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131
 
 BUNDLED WITH

data/Makefile

@@ -1,8 +1,13 @@
-.PHONY: check generate test tc
+.PHONY: check generate test tc integration
 
 # 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)
+integration:
+	INTEGRATION=1 bundle exec rspec spec/integration
+
 generate:
 	bundle exec ruby bin/generate
 

data/PLAN.md

@@ -1,7 +1,7 @@
-# Project Plan — typed GraphQL codegen for Ruby/Sorbet
+# Project Plan — GraphWeaver, typed GraphQL client for Ruby/Sorbet
 
-_Resume-from-here notes. The README is the lab notebook (findings); this is
-the plan. Update both when state changes._
+_Resume-from-here notes. README documents the product, NOTES.md is the
+research notebook this grew out of; this is the plan. Update on change._
 
 ## Vision
 
@@ -12,21 +12,40 @@ shape of every query result. Dynamic (eval) mode for development, build
 step for CI/static checking. Runtime deps: graphql + sorbet-runtime only
 (graphql-client is NOT a dependency; the exploration outgrew it).
 
-## State: working prototype, all green
+## State: v0.0.1 on rubygems; v0.0.2 accumulating on main
 
-`bundle exec rspec` (35 examples) + `bundle exec srb tc` + `bin/generate`
-(regenerates lib/generated/ from queries/; parity specs enforce freshness).
+`make check` = bin/generate (spec fixture regeneration; parity specs
+enforce freshness) + rspec + srb tc.
 
-Language coverage: queries, mutations, typed variables (kwargs on execute,
-optional-when-defaulted, enum/scalar serialization), fragments (inline,
-named, interface conditions), union- AND interface-typed fields
-(__typename dispatch, required at generation time), enums (T::Enum),
-custom scalars (name-keyed SCALAR_CASTS / SCALAR_SERIALIZERS registries).
+Language coverage: queries, mutations, typed variables (kwargs on
+execute, optional-when-defaulted), fragments (inline, named, interface
+conditions), union- AND interface-typed fields (__typename dispatch,
+required at generation time), enums (T::Enum), custom scalars via the
+ScalarType registry (register_scalar: codec inference off .parse/.load,
+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: kwarg — in-process schema or HttpExecutor (e2e spec
-against WEBrick). Federation supergraph SDL loads transparently (needs
+Transport: executor precedence per call → per module → baked const →
+GraphWeaver.executor; HttpExecutor (zero-dep) + opt-in FaradayExecutor
+(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)
+with extensible transport-error classification, schema_stale? staleness
+detection, errors_at/each_error/report field-level surfacing (entity
+ids resolved from partial data), and #to_h machine output throughout.
+Dynamic mode: GraphWeaver.parse (paths or raw strings, derived names,
+container-scoped constants) and GraphWeaver.execute one-shots.
+Schema fetching: SchemaLoader.introspect(executor, cache:, ttl:) off
+live endpoints; load takes paths, content, or Hashes.
+Testing (graph_weaver/testing + graph_weaver/rspec): FakeExecutor
+(schema-correct castable fakes, faker semantics, GraphQL-name
+overrides, corrupt:, fail_at: with null propagation), Failure canned
+executors + SequenceExecutor, cassettes with shape-preserving
+anonymization, rspec seed + auto_fake integration. Selection module is
+the single shared query-walk (codegen/fake/anonymizer).
+Federation supergraph SDL loads transparently (needs
 directive_defaults_patch until upstream fix ships).
+Live validation: make integration (GitHub + Countries APIs).
 
 ## Next steps (in rough order)
 
@@ -38,21 +57,32 @@ NOTES.md. Prior-art check partially answered: graphql-client PR #7
 Jan 2024 with users asking; schema-wide typing can't catch
 unfetched-field bugs or type unions/interfaces — the niche looks open.
 
+~~Input objects~~ DONE 2026-07-11: module-level T::Structs, serialize/
+to_h, hash coercion at the execute boundary.
+~~Release~~ 0.1.0 cut 2026-07-11 (breaking: execute returns the
+Response envelope; execute! for raise-or-result).
+
 1. Stable class naming design — names come from GraphQL type names per
    selection site; must not shift when unrelated selections are added
    (generated code is app-code API). Current: one-level field-name
-   disambiguation, then raise.
-2. Input objects as variables (raise NotImplementedError today) — likely
-   generated T::Structs with serialize.
-3. CLI entrypoint (graph_weaver generate --schema X --queries dir) —
+   disambiguation, then raise. Shipped in 0.1.0 as-is — a naming change
+   is fair game pre-1.0 but should land early.
+2. CLI entrypoint (graph_weaver generate --schema X --queries dir) —
    bin/generate is spec-fixture tooling, not shipped.
-4. Subscriptions (unsupported; raise).
-5. First release: 0.1.0 to rubygems once naming design settles.
-6. Nice-to-haves: __typename auto-injection (currently required manually
+3. Subscriptions (unsupported; raise). Recursive input types (raise).
+6. Parse/execute memoization: repeated GraphWeaver.parse/execute of the
+   same [schema, query] re-generates and re-evals every call (~3x the
+   cost of a cached module; benchmarked 2026-07-09) — memo keyed on
+   schema/query/name/executor, minding shared executor= mutation.
+   (Schema-side caching landed: SchemaLoader.introspect cache:/ttl: +
+   introspection_result primitive for Rails.cache et al. Possible
+   follow-up: re-introspect + retry once on validation-shaped
+   QueryErrors, since GraphQL has no standard schema-version signal.)
+7. Nice-to-haves: __typename auto-injection (currently required manually
    on abstract selections), fragment reuse across queries, directives on
    selections (@skip/@include make non-null fields nullable).
-7. Tapioca DSL compiler over dynamic mode (idea from graphql-client
-   PR #7): RBI the GraphWeaver::Codegen.load-eval'd modules so development mode
+8. Tapioca DSL compiler over dynamic mode (idea from graphql-client
+   PR #7): RBI the GraphWeaver.parse-eval'd modules so development mode
    gets static types without the bin/generate build step — tapioca is
    already in every Sorbet shop's workflow. Upstream's
    Tapioca::Dsl::Helpers::GraphqlTypeHelper is prior art for type mapping.

data/README.md

@@ -19,49 +19,93 @@ query($id: ID!) {
 ```
 
 ```ruby
-result = PersonQuery.execute(id: "1")
+result = PersonQuery.execute!(id: "1")   # typed result, or raises on errors (execute returns an envelope)
 
 result.person&.name       # => "Daniel" (typed String)
 result.person&.birthday   # => Date (custom scalars deserialize)
 result.person&.nmae       # => srb tc: Method `nmae` does not exist
 ```
 
-####  Features
+#### Features
 
-- **Queries and mutations** with typed variable kwargs — required vs optional falls out of nullability and defaults
-- **Fragments** (inline, named, interface conditions), **unions and interfaces** (member structs, `__typename` dispatch), **enums** (`T::Enum`), **custom scalars** (pluggable registry)
-- **Any schema source**: live schema class, introspection JSON, or SDL — including Apollo Federation supergraph SDL
-- **Any transport**: in-process schema execution (perfect for tests) or HTTP via the bundled executor — swap per call with `executor:`
-- **Dynamic mode** for development: `GraphWeaver::Codegen.load(...)` generates and evals on the fly, no build step
+- **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:`
+- **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
+#### Usage
 
 ```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")
+
 # generate from any schema source
 schema = GraphWeaver::SchemaLoader.load("schema.json")   # or .graphql SDL, or a live class
 
-source = GraphWeaver::Codegen.new(
+source = GraphWeaver::Codegen.generate(
   schema:,
-  executor_const: "MyApi::Executor",
   query: File.read("queries/person.graphql"),
   module_name: "PersonQuery",
-).generate
-
+)
 File.write("app/queries/person_query.rb", source)
 
 # at runtime
-executor = GraphWeaver::HttpExecutor.new("https://api.example.com/graphql")
-PersonQuery.execute(id: "1", executor:)
+PersonQuery.execute(id: "1")                        # uses GraphWeaver.executor
+PersonQuery.execute(id: "1", executor: other)       # or per call
 ```
 
-In development, skip the build step:
+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.
+
+Prefer Faraday? It's opt-in (`gem "faraday"` in your Gemfile):
 
 ```ruby
-PersonQuery = GraphWeaver::Codegen.load(schema:, executor_const: "...", query:, module_name: "PersonQuery")
+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:
+
+```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.execute(id: "1")
+
+# or one-shot, no module at all
+GraphWeaver.execute(schema:, query: "query($id: ID!) { person(id: $id) { name } }", variables: { id: "1" })
+```
+
+
+#### Dig deeper
+
+- **[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
+- **[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
+- **[Testing](docs/testing.md)** — schema-correct fakes, failure simulation,
+  cassettes with anonymized capture, rspec integration
+
 ----
 ## Installation
 
@@ -79,7 +123,8 @@ gem install graph_weaver
 ----
 ## Development
 
-`make check` — regenerate spec fixtures, run specs, typecheck.
+- `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

data/docs/errors.md

@@ -0,0 +1,106 @@
+# Errors
+
+`execute` returns a typed **`Response` envelope** rather than raising on GraphQL
+errors — so partial data and top-level `extensions` (cost, throttle) survive.
+`execute!` is the shortcut when you just want the result:
+
+```ruby
+PersonQuery.execute!(id: "1")   # => Result, or raises QueryError  (== execute(...).data!)
+
+response = PersonQuery.execute(id: "1")   # => GraphWeaver::Response[Result]
+response.data           # T.nilable(Result) — typed, present even on partial success
+response.errors         # Array[GraphWeaver::GraphQLError]
+response.errors?        # any top-level errors?
+response.extensions     # { "cost" => … } — rides on success too
+response.data!          # the Result, or raise GraphWeaver::QueryError
+```
+
+The envelope is a single generic `GraphWeaver::Response[Result]` — `response.data`
+stays fully typed to *this* query's result, no per-query wrapper class.
+
+Every `GraphQLError` exposes `#message`, `#locations`, `#path`, `#extensions`,
+and `#code` (`extensions["code"]`) — match on the **code**, not the message
+string (`response.errors.first.code == "THROTTLED"`).
+
+Everything GraphWeaver raises descends from `GraphWeaver::Error`, split by where
+it failed:
+
+| Class | When |
+|-------|------|
+| `TransportError` | never reached the server — DNS, connection refused, TLS, timeout |
+| `ServerError` | reached it, non-2xx HTTP — `#status`, `#body` |
+| `QueryError` | 200 body with top-level GraphQL errors — `#errors`, `#data`, `#extensions`, `#codes` |
+| `ValidationError` | build time: the query didn't validate against the schema (also an `ArgumentError`) |
+
+```ruby
+begin
+  person = PersonQuery.execute!(id: "1").person
+rescue GraphWeaver::TransportError
+  retry                                   # network blip
+rescue GraphWeaver::ServerError => e
+  raise if e.status < 500                 # backoff on 5xx only
+rescue GraphWeaver::QueryError => e
+  e.codes.include?("THROTTLED") ? backoff : raise
+end
+```
+
+What counts as a `TransportError` is an **extensible set** — each transport
+seeds its own network exceptions (`Errno::*`, `SocketError`, timeouts, TLS; the
+Faraday executor adds its own), and you can register more so a custom adapter's
+or connection pool's failure gets the same treatment:
+
+```ruby
+GraphWeaver.register_transport_error(ConnectionPool::TimeoutError)
+GraphWeaver.transport_errors << MyAdapter::ResetError   # it's just a Set
+```
+
+Business/validation failures returned *as data* (Shopify-style `userErrors { field
+message code }`) aren't errors here — they're just fields you selected, so they
+deserialize onto `response.data` like anything else and you inspect them there.
+
+The one-shot `GraphWeaver.execute` / `execute!` mirror this: `execute` returns
+the envelope, `execute!` the result-or-raise.
+
+
+## Programmatic surfacing
+
+Every error is dual-surface: `#message` for humans, `#to_h` for machines — a
+JSON-ready hash (error class, per-error `path`/`code`/`locations`/`extensions`)
+you can nest straight into a log line or an API response.
+
+Field-level tooling lives on both `Response` and `QueryError`:
+
+```ruby
+response.errors_at("person.email")      # errors touching a path (prefix match)
+response.each_error do |field, errors|  # grouped by index-stripped field
+  form.add_error(field, errors.map(&:message))
+end
+
+response.report
+# { "person.pets.name" => {
+#     "messages" => ["name hidden"], "codes" => ["PRIVATE"],
+#     "entity_ids" => ["7", "9"],    # resolved by walking paths through partial data
+#     "errors" => [ ...full to_h detail... ] },
+#   nil => { "codes" => ["DOWN"], ... } }   # global errors under nil
+```
+
+`GraphQLError#field` strips list indices (`people.3.email` → `people.email`) —
+the stable grouping key; the raw `#path` keeps indices for exact location.
+
+## Stale schemas
+
+GraphQL has no schema-version signal, so a schema change surfaces as the
+server rejecting your query's shape. `response.schema_stale?` /
+`QueryError#schema_stale?` detect validation-shaped rejections (Apollo's
+`GRAPHQL_VALIDATION_FAILED` code, or the message patterns graphql-ruby and
+GitHub use), and the raised message says what to do: regenerate modules and/or
+refresh the schema cache.
+
+## Cast failures
+
+When wire data disagrees with the types the schema promised at generation time
+(a nil where non-null was declared, a malformed scalar, an unknown enum value),
+casting raises `GraphWeaver::TypeError` naming the failing generated struct,
+with the original exception as `#cause`. Simulate one in tests with
+`FakeExecutor.new(schema:, corrupt: "Person.birthday")` — see
+[testing](testing.md).