graph_weaver 0.4.6 → 0.5.1

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graph_weaver
 version: !ruby/object:Gem::Version
-  version: 0.4.6
+  version: 0.5.1
 platform: ruby
 authors:
 - Daniel Pepper
@@ -219,23 +219,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: A typed GraphQL client for Ruby — generate Sorbet T::Structs from queries,
-  with federation, extensibility, and testing in mind
+description: Your .graphql files, compiled into Sorbet types — and the fakes to test
+  them.
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - ".yardopts"
 - CHANGELOG.md
-- CLAUDE.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
-- Makefile
-- NOTES.md
-- PLAN.md
 - README.md
 - docs/cassettes.md
+- docs/editors.md
 - docs/errors.md
 - docs/federation.md
 - docs/generated_modules.md
@@ -245,30 +242,44 @@ files:
 - docs/scalars.md
 - docs/testing.md
 - docs/transports.md
+- docs/upgrading.md
 - graph_weaver.gemspec
+- lib/generators/graph_weaver/install_generator.rb
 - lib/graph_weaver.rb
 - lib/graph_weaver/client.rb
 - lib/graph_weaver/codegen.rb
+- lib/graph_weaver/codegen/aliases.rb
 - lib/graph_weaver/codegen/emit.rb
 - lib/graph_weaver/codegen/enum_type.rb
 - lib/graph_weaver/codegen/nodes.rb
 - lib/graph_weaver/codegen/scalar_type.rb
+- lib/graph_weaver/codegen/type_helpers.rb
 - lib/graph_weaver/errors.rb
+- lib/graph_weaver/federation.rb
 - lib/graph_weaver/hints.rb
+- lib/graph_weaver/in_process.rb
 - lib/graph_weaver/inflect.rb
 - lib/graph_weaver/input_struct.rb
 - lib/graph_weaver/logging.rb
+- lib/graph_weaver/parsing.rb
+- lib/graph_weaver/query_module.rb
 - lib/graph_weaver/railtie.rb
+- lib/graph_weaver/representation.rb
 - lib/graph_weaver/response.rb
 - lib/graph_weaver/retry.rb
 - lib/graph_weaver/rspec.rb
 - lib/graph_weaver/schema_loader.rb
+- lib/graph_weaver/schemas.rb
 - lib/graph_weaver/selection.rb
 - lib/graph_weaver/tasks.rb
 - lib/graph_weaver/testing.rb
 - lib/graph_weaver/testing/cassette.rb
+- lib/graph_weaver/testing/coverage.rb
 - lib/graph_weaver/testing/failure.rb
 - lib/graph_weaver/testing/fake_client.rb
+- lib/graph_weaver/testing/fake_subgraph.rb
+- lib/graph_weaver/testing/router.rb
+- lib/graph_weaver/testing/subgraphs.rb
 - lib/graph_weaver/testing/values.rb
 - lib/graph_weaver/transport.rb
 - lib/graph_weaver/transport/faraday.rb
@@ -277,7 +288,12 @@ files:
 homepage: https://github.com/dpep/graph_weaver
 licenses:
 - MIT
-metadata: {}
+metadata:
+  bug_tracker_uri: https://github.com/dpep/graph_weaver/issues
+  changelog_uri: https://github.com/dpep/graph_weaver/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/dpep/graph_weaver/tree/main/docs
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/dpep/graph_weaver
 rdoc_options: []
 require_paths:
 - lib
@@ -294,5 +310,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: GraphWeaver
+summary: A typed GraphQL client for Ruby
 test_files: []

data/CLAUDE.md

@@ -1,69 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## What this is
-
-A typed GraphQL client for Ruby: generates `# typed: strict` Ruby (nested
-`T::Struct`s + a typed `execute`) from your queries, checked against the schema
-at generation time. Sorbet is core to the product.
-
-## Sorbet typing policy — type by value, not for coverage
-
-Sorbet being core does **not** mean every file should be `# typed: strict`. Type
-where it pays off in developer experience; leave the rest at `# typed: true`.
-
-- **Strict (full sigs) — developer-facing contracts.** The types users touch:
-  `response.rb` (the envelope every `execute` returns), the error hierarchy
-  (`errors.rb`), and the **generated code** (emitted `# typed: strict`). Concrete
-  types here give downstream apps real call-site checking + autocomplete — that's
-  the product.
-- **`# typed: true` (loose) — dynamic / boundary internals.** The codegen
-  (`codegen.rb`, `codegen/nodes.rb`, `codegen/emit.rb`, `codegen/scalar_type.rb`,
-  `codegen/enum_type.rb`) walks graphql-ruby's approximately-typed AST and builds
-  modules/strings dynamically; `client.rb` wraps a graphql-ruby schema and a
-  duck-typed transport. Strict here is ~all `T.untyped` — paperwork that documents
-  shape without catching anything. **Don't promote these to strict.**
-- Rule of thumb: if a sig would be mostly `T.untyped`, it isn't worth writing.
-  Concrete types = value; `T.untyped` sigs = paperwork.
-- `railtie.rb` / `tasks.rb` are `# typed: ignore` (Rails/Rake DSL).
-
-## Design invariants (don't "fix" these)
-
-- **The client slot is duck-typed.** A transport, `Retry`, a live graphql-ruby
-  schema class, or a test fake all satisfy one contract —
-  `execute(query, variables:) => {"data" => ..., "errors" => ...}` — with no
-  shared base class. **Don't formalize it as a strict Sorbet interface**: a
-  graphql-ruby `Schema` class fits the slot without inheriting anything, and a
-  strict interface would exclude it. This is why the transport/client seams stay
-  loosely typed.
-- **Codegen is query-driven.** Structs are generated per selection set, only for
-  the types a query actually touches — not the whole schema (so extra schema
-  types, e.g. federation `join__*`, generate no code).
-- **Leaf codecs vs composite decoration.** `register_scalar` / `register_enum`
-  *define/replace* how a leaf deserializes (its Ruby shape is fixed);
-  `extend_type` only *decorates* a generated composite struct with mixins — it
-  can't replace one, because a composite's shape varies per query. Don't add a
-  "replace a composite's deserializer" path.
-
-## Green before commit
-
-```sh
-bundle exec rspec        # full suite
-bundle exec srb tc       # Sorbet typecheck (CI gates on this too)
-```
-
-Both must pass. Sorbet sigs are runtime-checked by sorbet-runtime, so a wrong
-sig surfaces as an rspec failure, not only a `srb tc` error — a green suite
-validates the sigs against real usage.
-
-## Version bumps
-
-Bump `lib/graph_weaver/version.rb` and, in the **same commit**:
-
-- update `Gemfile.lock` (the gem pins its own version there; CI runs a frozen
-  `bundle install`, which fails at the *setup* step with exit code 16 — before
-  tests — if the lock is stale), and
-- add a `CHANGELOG.md` entry.
-
-`gem push` (the actual RubyGems release) is a separate, manual step.

data/Makefile

@@ -1,23 +0,0 @@
-.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; federation boots an Apollo gateway — node)
-integration:
-	INTEGRATION=1 bundle exec rspec spec/integration
-
-generate:
-	bundle exec ruby bin/generate
-
-test:
-	bundle exec rspec
-
-tc:
-	bundle exec srb tc
-
-# preview what rubydoc.info will render
-docs:
-	bundle exec yard doc
-	open doc/index.html

data/NOTES.md

@@ -1,182 +0,0 @@
-Research notes — graphql-client exploration → GraphWeaver
-======
-
-**What this is now:** a working prototype of a standalone, Sorbet-typed
-GraphQL client for Ruby — "graphql-codegen for Ruby". `.graphql` queries +
-a schema (live class, introspection JSON, or SDL) generate `# typed: strict`
-Ruby: nested `T::Struct`s, casting code, and a typed `execute`, so `srb tc`
-sees the exact shape of every query result. It is **not** a graphql-client
-extension: generated code depends only on `graphql` (generation time) and
-`sorbet-runtime` (runtime); transport is a pluggable `executor:` (in-process
-schema or the bundled `HttpExecutor`).
-
-Start with `PLAN.md` for current state and next steps. Key files:
-`lib/struct_codegen.rb` (the generator), `queries/` → `bin/generate` →
-`lib/generated/` (the build loop), `StructCodegen.load` (build-free dynamic
-mode for development).
-
-**How it got here:** the repo began as an exploration of
-[graphql-client](https://github.com/github-community-projects/graphql-client)
-internals — could its class-generation layer be swapped to emit custom
-classes? (Yes: the `StructTypes` spike below.) The per-query codegen
-approach then outgrew graphql-client entirely, and everything below the
-next heading is preserved as the lab notebook: findings in chronological
-order, each backed by a spec.
-
-The specs are the documentation — each one asserts an observed behavior:
-
-```sh
-bundle exec rspec
-```
-
-## Findings, in exploration order
-
-- The client runs fine against an in-process schema: `GraphQL::Client.new(schema: Schema, execute: Schema)` — no HTTP involved.
-- Each query selection gets its own dynamically generated wrapper class (subclass of `GraphQL::Client::Schema::ObjectClass`); fields are snake_case readers, and unselected fields raise instead of returning nil.
-- **Custom scalars are deserialized automatically** when the client is built from a live schema class: the reader casts wire values through the scalar's `coerce_input` (e.g. `"1990-06-15"` → `Date`). This is the built-in hook for producing rich Ruby values.
-  - Caveat: this only works with `schema:` as a live schema class. A schema loaded from an introspection JSON dump has no coercion logic, so scalars would stay raw.
-- `to_h` returns the raw wire values (strings), not the casted ones — hydration code should read via the typed readers, not `to_h`.
-- Hydrating into `T::Struct`s is straightforward manually; the interesting next step is generating the structs (or a generic hydrator) from the parsed query definition, since the client already knows each selection's shape and types.
-
-## Swapping the class-generation layer (answered: yes)
-
-`lib/struct_types.rb` + `spec/struct_types_spec.rb` prove the generation layer
-can be replaced wholesale — the client deserializes straight into generated
-`T::Struct`s, no `ObjectClass` involved.
-
-How the pipeline hangs together (graphql-client 0.26.0):
-
-- `Client#initialize` builds the types module: `@types = Schema.generate(schema)`
-  (`attr_reader :types`, no setter — swap via `instance_variable_set` or a subclass).
-- `Client#parse` → `Definition#initialize` calls
-  `client.types.define_class(definition, ast_nodes, type)` and stores the result
-  as `definition.schema_class`. This is the ONLY thing the client asks of the
-  types module.
-- `Client#query` → `definition.new(data, errors)` → `schema_class.new(data, errors)`.
-- Everything below that is the `cast(value, errors)` protocol, composed
-  recursively per the query selection (NonNull/List wrappers, scalars, objects).
-
-So the replacement contract is just:
-- `define_class(definition, ast_nodes, type)` returning casters
-- casters respond to `cast(value, errors)`
-- the top-level caster must satisfy `Definition#new`'s case dispatch, which
-  tests `===` against the `GraphQL::Client::Schema::ObjectType` module —
-  including that module in your caster class is enough, plus a
-  `new(data, errors)` method
-
-Gotchas found:
-- the client injects `__typename` into every selection (`QueryTypename`), so a
-  custom generator must skip/handle `__`-prefixed fields
-- scalar casting reuses the schema type's `coerce_isolated_input` — same hook
-  the stock `ScalarType` uses
-- prop nullability comes for free from the type walk: everything is
-  `T.nilable` unless wrapped in NON_NULL
-
-## Sorbet
-
-- `sorbet` + `tapioca` are set up (`bundle exec srb tc` is green); rbis in `sorbet/rbi/gems`
-- `struct_types.rb` typechecks at `# typed: true`
-- generated structs are real `T::Struct`s: schema-derived prop types
-  (`T.nilable(Date)`, `T::Array[StructTypes::Pet]`) and runtime type
-  enforcement on bad wire data
-
-## Codegen: srb tc sees query result types (answered: yes)
-
-`lib/struct_codegen.rb` goes one step further than the runtime swap: it
-emits plain `# typed: strict` Ruby source from a query + schema — nested
-`T::Struct` classes, fully generated `from_h` casting code (no runtime
-reflection), and a sig'd `execute`.
-
-- source of truth: `queries/*.graphql`; regenerate with `bin/generate`
-  into `lib/generated/`; a spec asserts the checked-in output is current
-- queries are validated against the schema at generation time
-- `srb tc` statically checks result access end to end:
-  `result.person&.nmae` → `Method nmae does not exist on
-  PersonQuery::Result::Person`
-- custom scalar deserialization is inlined by the generator
-  (`Date.iso8601(...)`) via a scalar registry; nullability and list
-  casting come from the NON_NULL/LIST walk
-- note: generated `execute` runs against the schema directly, replacing
-  graphql-client at runtime entirely — the client's remaining value here
-  would be its HTTP adapter, which the generated code could target instead
-
-## Fragments & unions (answered for codegen)
-
-`queries/search.graphql` + `lib/generated/search_query.rb` exercise the
-design:
-
-- inline fragments and named fragment spreads are flattened into their
-  matching member's selection (exact type-name condition match; interface
-  conditions still open)
-- unions emit a module per selection site: one `T::Struct` per possible
-  type, a `Type = T.type_alias { T.any(...) }`, and a `from_h` that
-  dispatches on `__typename` — codegen refuses union selections that
-  don't select `__typename`
-- every possible type gets a member struct even without a fragment (it
-  still carries `__typename`), so dispatch is total
-
-## Introspection / __type metadata
-
-- `__type` / `__schema` queries work against the demo schema as expected
-  (see `spec/introspection_spec.rb` for the shapes)
-- the key result: `GraphQL::Schema.from_introspection(Demo::Schema.as_json)`
-  produces a schema that codegen runs against **byte-identically** — so
-  generation works for remote APIs known only via an introspection dump.
-  Custom scalar handling survives because the codegen scalar registry is
-  keyed by type *name*, unlike runtime `coerce_input` which needs the live
-  schema class (the caveat that broke graphql-client's scalar casting)
-
-## Federation / supergraph
-
-- join__/link-annotated supergraph SDL parses via
-  `GraphQL::Schema.from_definition`, and codegen runs against it
-  unchanged — the directives are transparent to result typing
-  (`spec/federation_spec.rb` generates from a mini supergraph and casts a
-  response with no live subgraphs)
-- gotcha: graphql-ruby's SDL builder does not apply directive-argument
-  defaults, so real Apollo `join v0.3` SDL (non-null defaulted args like
-  `extension: Boolean! = false`) fails to load unless those args are
-  provided or the directive defs are trimmed — a compatibility issue a
-  real tool would need to patch around
-- client-side, federation needs nothing more: you query the router like
-  any schema. The *server-side* angle (emitting `@key`/`@external` via
-  apollo-federation) is a separate exploration — potentially relevant to
-  autographql
-
-## Round 2: enums, interface conditions, loaders, dynamic mode, HTTP
-
-- **enums** generate `T::Enum` classes (`Species::Dog`), deserialized via
-  `Species.deserialize(...)` in `from_h`; values sorted so output is
-  deterministic across schema sources
-- **interface fragment conditions** (`... on Named { name }`) apply via
-  `schema.possible_types`, not just exact type-name match. Interface-typed
-  *fields* (a field returning `Named`) are still open — they'd emit like
-  unions with `__typename` dispatch
-- **SchemaLoader** accepts both formats a remote service can hand you:
-  introspection dump (`.json`) or SDL (`.graphql`/`.gql`); both generate
-  byte-identically to the live schema class
-- **dynamic mode**: `StructCodegen.load(...)` generates + evals in one
-  step — no build artifact, same runtime semantics, right for development
-  or one-off scripts. Tradeoff: the module is invisible to `srb tc`, so
-  static checking of result access needs the build step
-- **HTTP transport**: generated `execute` takes `executor:` — anything
-  with `execute(query, variables:)` returning `{"data" => ...}`.
-  `HttpExecutor` (Net::HTTP POST) runs the same generated structs against
-  a live server (`spec/http_spec.rb` proves it against a local WEBrick
-  serving Demo::Schema)
-- **directive defaults gap**: root cause found —
-  `BuildFromDefinition#prepare_directives` passes only usage-site args
-  while `Directive#initialize` validates all defined args without
-  applying `default_value`. `lib/directive_defaults_patch.rb` prepends
-  the fix; the federation spec now loads the *real* join v0.3 SDL.
-  Present in graphql 2.6.3 (latest) — worth an upstream issue/PR
-
-## 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
-- mutations/subscriptions (only query operations generate)

data/PLAN.md

@@ -1,144 +0,0 @@
-# Project Plan — GraphWeaver, typed GraphQL client for Ruby/Sorbet
-
-_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
-
-A "graphql-codegen for Ruby": `.graphql` queries + a schema (live class,
-introspection JSON, or SDL) → checked-in `# typed: strict` Ruby — nested
-T::Structs, generated casting, typed execute — so `srb tc` sees the exact
-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: v0.0.1 on rubygems; v0.0.2 accumulating on main
-
-`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), 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 precedence per call → per module → baked const →
-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)
-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)
-
-~~Extraction~~ DONE 2026-07-07: this repo IS the gem now — GraphWeaver,
-github.com/dpep/graph_weaver, rspec-uuid conventions throughout. The
-graphql-client spikes live in git history (tag: `exploration`) and
-NOTES.md. Prior-art check partially answered: graphql-client PR #7
-(tapioca compiler over schema-wide dynamic classes) stalled since
-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. 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.
-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).
-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.
-
-## External dependencies
-
-- rmosolgo/graphql-ruby#5659 (directive-argument defaults fix; our branch
-  `directive-argument-defaults` in ~/code/lib/ruby/graphql, pushed to the
-  dpep fork, PR in draft). When it ships in a release: bump graphql,
-  delete lib/graph_weaver/directive_defaults_patch.rb + its requires (TODO in file).
-
-## Gotchas worth remembering
-
-- graphql-ruby to_definition/from_introspection reorder enum values and
-  possible_types — codegen sorts both; keep any new emission deterministic
-- schemas built from introspection/SDL have no scalar coercion or
-  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)
-
-Generated-module size (2026-07-12, post-0.2.0): input structs are now
-table-driven (InputStruct runtime + FIELDS) — the PokeAPI filtered-query
-module dropped 29,233 -> 11,562 lines. The floor is ~2 lines/field
-(typed const + FIELDS entry). Remaining lever if it matters again:
-shared input structs emitted once per schema instead of per module.
-
-
-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).