graph_weaver 0.4.4 → 0.5.0

data/docs/scalars.md

@@ -9,10 +9,8 @@ Ruby object (and serializes back when used as a variable). A field typed
 GraphWeaver.register_scalar("Money", Money, requires: "bigdecimal")
 ```
 
-Registrations are global by default. A [client](transports.md) scopes
-them: `client.register_scalar(...)` overlays the global registry for that
-client's generation only — so two servers can disagree about what a
-`DateTime` is, and neither leaks into the other.
+Registration is global and codegen-time: `rake graph_weaver:generate` reads the
+same registry an initializer writes, so register before you generate.
 
 Pass a `Type.field` **coordinate** instead of a scalar name to override just
 that one field — so the same scalar can deserialize as different Ruby types
@@ -23,9 +21,9 @@ GraphWeaver.register_scalar("ISO8601DateTime", Time)   # the default, everywhere
 GraphWeaver.register_scalar("User.birthday", Date)     # this field only
 ```
 
-A field override wins over the scalar-name registration; both stack the same
-global-then-client way. (GraphQL names can't contain `.`, so the coordinate is
-unambiguous — and it's validated against the schema, so a typo'd field raises.)
+A field override wins over the scalar-name registration — which is also how two
+servers that disagree about a `DateTime` coexist in one process. Coordinates are
+validated against the schema, so a typo'd field raises.
 
 Pass a real class as `type:` and the cast/serialize are **inferred** from it by
 probing the deserialize side and pairing its serializer:
@@ -35,12 +33,9 @@ probing the deserialize side and pairing its serializer:
 | `.parse`          | `Type.parse(v)` | `v.to_s`     |
 | `.load`           | `Type.load(v)`  | `Type.dump(v)` |
 
-so the common case needs nothing more. Probing the *deserialize* side is
-deliberate — every object has `#to_s`, so inferring off it would wrongly wrap
-plain types like `String`/`Integer`; requiring a `.parse`/`.load` the type
-actually defines avoids that (and is why the built-in scalars — `Date`, `ID`,
-`Int`, and friends, pre-registered and detailed below — can be registered with
-their real class constants). Override explicitly when you need to:
+so the common case needs nothing more. A type defining neither `.parse` nor
+`.load` stays pass-through rather than getting wrapped. Override explicitly when
+you need to:
 
 - a `Symbol` method name, nothing to misspell: `cast: :load` → `Money.load(expr)`,
   `serialize: :to_json` → `expr.to_json`
@@ -54,7 +49,7 @@ a real class (so the runtime is loaded), each path is also `require`d at
 registration — a typo fails now, not in the generated file.
 
 Pass `coerce: true` to let a variable of this scalar accept **either** the value
-object **or** its raw input, normalizing the latter through the cast:
+object **or** its raw input, normalizing the latter before it goes on the wire:
 
 ```ruby
 GraphWeaver.register_scalar("Money", Money, coerce: true)
@@ -63,38 +58,42 @@ StoreQuery.execute(budget: "12.00")          # Money.parse("12.00") under the ho
 StoreQuery.execute(budget: Money.new(1200))  # passed straight through
 ```
 
-Bad input still explodes (the cast raises), so some safety survives; coercion
-needs both a cast and a serialize. Off by default — the strict typed kwarg is the norm.
+`GraphWeaver.auto_coerce = true` is the same switch for every scalar at once —
+set it any time before you generate; an explicit `coerce:` on a registration
+always wins. Off by default either way: the strict typed kwarg is the norm.
 
-`coerce:` also takes a **Symbol** naming a conversion method, for built-ins where
-a plain method is the whole story — `coerce: :to_f` makes a variable accept
-`5`/`"5"` and `.to_f` it, sending a native number (not `"5.0"`) on the wire. The
-convertible built-ins already know theirs (`Float`→`:to_f`, `Int`→`:to_i`,
-`ID`/`String`→`:to_s`), so rather than opting in each, flip the default:
-
-```ruby
-GraphWeaver.auto_coerce = true
-```
-
-Resolved lazily at generation time (set it any time before you generate),
-it gives convertible built-ins their conversion and any scalar with a full
-cast/serialize pair (`Date`, your `Money`) parse-style coercion; an explicit
-`coerce:` on a registration always wins. `Boolean` has no lossless
-one-method conversion, so it stays strict.
+*How* a scalar coerces isn't yours to pick — the scalar already knows. `Int` and
+`Float` convert (`"5"` → `5`, sent as a native number); anything with a full
+cast/serialize pair (`Date`, your `Money`) parses, and bad input still explodes
+because the cast raises. A pass-through scalar — `String`, `ID`, `Boolean` — has
+neither a conversion nor a codec pair, so it can't coerce at all: `coerce: true`
+on one raises rather than emitting a no-op.
 
 The built-in scalars (`Date`, `ID`, `Int`, …) are pre-registered through the
 same path (`Date` even carries its own `require "date"`), so a later
-`register_scalar` overrides them; `GraphWeaver.reset_scalars!` restores the
-defaults (`reset_scalars!(coerce: true)` restores them coercible) and
-`clear_scalars!` empties the registry. Register before generating — it's a
-codegen-time concern, baked into the emitted source.
+`register_scalar` overrides them.
+
+`GraphWeaver.reset_registrations!` is the clean slate between tests: built-in
+scalars restored, enum mappings and type helpers dropped. To reset one registry
+rather than all of them, `GraphWeaver::Codegen` has the pieces —
+`reset_scalars!` (restore the built-ins), `clear_scalars!` (empty the registry
+entirely), `reset_enums!`, `reset_type_helpers!`.
+
+A scalar you never register is not an error — it generates as `T.untyped` and
+the wire value passes through untouched. It is, though, the one hole in an
+otherwise exact result type, so generation names the holes at `info` (see
+[logging](logging.md)):
+
+```
+3 unregistered custom scalars → T.untyped: CountryCode, FuzzyDateInt, Json (register with GraphWeaver.register_scalar)
+```
 
 ## Enums: map onto your own T::Enum
 
-By default each generated module grows its own `T::Enum` per GraphQL
-enum — `AddPetQuery::Species`, `SearchQuery::Result::...::Species`, one
-per module that touches it. That's fine until your app has its own
-domain enum, and then the boundary shuffle starts:
+By default a schema enum generates one `T::Enum` per schema, shared by every
+query module that touches it (`GraphQLTypes::Species`, aliased as
+`AddPetMutation::Species`). That's fine until your app has its own domain
+enum, and then the boundary shuffle starts:
 
 ```ruby
 # your domain already speaks PetKind — it's in your models, your
@@ -105,28 +104,24 @@ end
 
 # without a mapping, every call site converts by hand, in both directions
 kind = PetKind.deserialize(pet.species.serialize.downcase)      # response -> domain
-AddPetQuery.execute!(species: kind.serialize.upcase)            # domain -> wire
+AddPetMutation.execute!(species: kind.serialize.upcase)            # domain -> wire
 ```
 
-Two enums for one concept, glue at every crossing, and each generated
-module has its *own* incompatible `Species`, so a pet from `SearchQuery`
-and a pet from `AddPetQuery` don't even compare. Register the mapping
-once and the seam disappears — generated code speaks your enum
-everywhere, casting wire values in and serializing members out:
+Register the mapping once and the seam disappears — generated code speaks your
+enum everywhere, casting wire values in and serializing members out:
 
 ```ruby
-GraphWeaver.register_enum("Species", PetKind)                # global
-api.register_enums("Species" => PetKind, "Role" => Role)     # or per client, in bulk
+GraphWeaver.register_enum("Species", PetKind)
 
 pet.species                                   # => PetKind::Dog — compare, case, persist directly
 pet.species == other_pet.species              # same type across every query
-AddPetQuery.execute!(species: PetKind::Cat)   # or "CAT" — members and wire values both work
+AddPetMutation.execute!(species: PetKind::Cat)   # or "CAT" — members and wire values both work
 ```
 
 **When to reach for it**: the enum has a life outside the API — it's
-persisted, matched in business logic, or shared across queries. **When
-not to bother**: display-only values you read and forget; the per-module
-generated enums are self-contained and need zero setup.
+persisted or matched in business logic. **When not to bother**: values you
+only read back out of responses; the generated enum is already one type
+across every query and needs zero setup.
 
 The mapping is inferred by name (`"CAT"` ↔ `PetKind::Cat`,
 case/underscore-insensitive against each member's serialized value), so
@@ -151,89 +146,7 @@ Two safety properties do the real work:
 
 The translation tables are emitted into the generated source
 (`SPECIES_FROM_WIRE` / `SPECIES_TO_WIRE`) — reviewable in the diff, no
-runtime registry. And because registration can be client-scoped, two
-servers with different ideas of `"Species"` can map onto different (or
-the same) domain enums without touching each other.
-
-## Type helpers: your logic on generated structs
-
-Derived values (display names, emoji, predicates) belong next to the
-data but not *in* it — rewriting wire values on the way in destroys the
-raw truth. Register a plain module and every struct generated from that
-GraphQL type includes it, whatever query it appears in:
-
-```ruby
-module PetHelpers
-  def adult? = birthday && birthday < Date.today << 24
-  def display_name = adult? ? "#{name} 🦴" : "#{name} 🐶"
-end
-
-GraphWeaver.extend_type("Pet", PetHelpers)   # or api.extend_type(...)
-
-pet.display_name   # => "Shelby 🦴"
-pet.name           # => "Shelby" — the wire value stays honest
-```
-
-The methods live on the struct, so they see its wire fields at runtime and
-fakes/cassettes get the behavior automatically; registrations are additive
-(global plus client-scoped stack). One caveat on *static* typing, though:
-`srb tc` checks a mixin's method bodies in the module's own scope, not the
-including struct's — so a helper that reads a wire field (`name`, `birthday`)
-doesn't resolve it and fails with "method does not exist on the module." Write
-such a helper at `# typed: false`, or reach the field through `T.unsafe(self)`
-— either way its body isn't statically checked against the selection. (Sorbet's
-`requires_ancestor` is the escape in principle, but it needs an experimental
-flag and a concrete ancestor, which a per-query struct isn't.) The only place a
-field-reading derivation type-checks natively is *inside* the struct body, where
-the field is in scope — which is codegen's job, not a mixin's.
-
-For quick decoration, build the mixin inline — the block is
-`module_eval`'d into a fresh module auto-named under
-`GraphWeaver::TypeHelpers` so generated files can reference it:
-
-```ruby
-api.extend_type("Pet") do
-  def display_name = "#{name} 🐶"
-end
-```
-
-Same runtime behavior, less static reach: the block becomes a runtime module
-with no source on disk, so `srb tc` can't see its methods at all — fine in
-dynamic `parse`, but in a checked-in `# typed: strict` file it's an unresolved
-reference. Prefer a named module (and mind the field-access caveat above) where
-static checking matters — complexity on demand.
-
-### Flat accessors with `alias:`
-
-The one derivation the generator can type for you is a plain projection — a
-selected field, possibly nested, exposed under a flat accessor. `alias:` emits a
-sig'd delegator *into the struct body*, where the field is in scope, so it's
-fully checked (the thing a mixin can't be):
-
-```ruby
-GraphWeaver.extend_type("Widget", alias: { tag: "meta.tag" })
-
-# generated on the Widget struct:
-#   sig { returns(T.nilable(String)) }
-#   def tag = meta&.tag
-```
-
-So a hand-written value object that only existed to expose `tag` flat over
-`data.dig("meta", "tag")` drops away — the generated struct answers `.tag`
-directly. Forms:
-
-```ruby
-alias: { tag: "meta.tag" }              # explicit accessor name
-alias: "meta.tag"                       # accessor named after the last segment (`tag`)
-alias: ["meta.tag", "meta.color"]       # several at once
-alias: { label: "name", tag: "meta.tag" }
-```
+runtime registry.
 
-The path is the Ruby accessor chain (`meta.tag`), typed from the selection: any
-nullable hop makes the accessor nilable and inserts `&.`; the leaf can be a
-scalar, enum, or nested struct. It's validated against each query at generation —
-an unselected or misspelled segment (`did you mean 'tag'?`), a path through a
-list, or a name that collides with a real field all fail with a pointed error.
-Registrations stack and are client-scopable, like the mixin forms. For anything
-beyond a passthrough projection — real logic, still typed — reopen the generated
-struct in your own file and add sig'd methods; Sorbet merges the bodies.
+Decorating a generated *struct* with your own methods is the sibling API —
+`extend_type`, in [generated modules](generated_modules.md#type-helpers).

data/docs/testing.md

@@ -1,22 +1,162 @@
 # Testing
 
-Everything here is a *client* — the one interface queries run
-through: anything with `execute(query, variables:)` returning
-`{"data" => ..., "errors" => ...}` (see [transports](transports.md)).
-Fakes, failures, and cassettes all slot in wherever a real transport
-would.
+One line in your spec helper:
 
-`require "graph_weaver/rspec"` from your spec helper (or
-`graph_weaver/testing` outside rspec — never in production) for a
-zero-setup fake backend. `FakeClient` fabricates
-schema-correct responses for whatever query arrives: real enum values,
-valid `__typename` members, iso8601 date scalars — every fake casts
-cleanly through your generated structs.
+```ruby
+require "graph_weaver/rspec"
+```
+
+(In Rails, put it **above** the `spec/support` glob in `rails_helper.rb` —
+rspec-rails requires those partway through, and a support file mentioning
+`GraphWeaver::Testing` before this line dies on `NameError`.)
+
+Then **one tag says what an example runs against** — on the example, or on
+the group it belongs to, since rspec metadata inherits:
 
 ```ruby
-fake = GraphWeaver::Testing::FakeClient.new(schema:)
+describe "checkout", graphql: :router do
+  it "stitches the dashboard" do … end     # every example here, too
+end
+
+it "renders the empty state", graphql: :fake do … end
+it "authorizes drafts",       graphql: :in_process do … end
+```
+
+| mode | reach for it when | what it costs |
+|---|---|---|
+| `graphql: :fake` | most unit tests — you need *a* well-shaped response | no resolver code runs |
+| `graphql: :in_process` | the point of the test is that your resolver logic works | slower; needs a live schema class |
+| `graphql: :router` | the same, across a federated graph | needs a composed supergraph; [refuses](federation.md#what-it-refuses) shapes it can't plan faithfully |
+| [cassettes](cassettes.md) | pinning a real server's exact response | must be re-recorded when the query changes |
+
+The tag installs its client as `GraphWeaver.client` for that example, so
+generated modules run against it with zero per-test setup. (Generate them
+*without* a baked `client:` — a module that has one never consults
+`GraphWeaver.client`.) `rspec --tag graphql:router` runs one mode's
+examples; an untagged example is left alone unless you set
+`config.default_mode`, and **`graphql: false` opts one back out** of that
+default.
+
+`GraphWeaver.client` is **snapshotted before every example and restored
+after** — tagged, untagged or opted out, and whatever the example did to
+it. So building your own client is a plain assignment, cleaned up like a
+tagged one:
+
+```ruby
+before { GraphWeaver.client = GraphWeaver::Testing::Failure.throttled }
+```
+
+Everything here is a *client* — the one interface queries run through:
+anything with `execute(query, variables:, operation_name:)` returning
+`{"data" => ..., "errors" => ...}` (see [transports](transports.md)). Fakes,
+the router, failures, and cassettes all slot in wherever a real transport
+would, so they work outside rspec too (`require "graph_weaver/testing"` —
+never from production code). Outside the tags there's no `GraphWeaver.client`
+to lean on, so parse from the fake or the router itself — anything holding a
+schema parses against it, and the module runs on what parsed it:
+
+```ruby
+router = GraphWeaver::Testing::Router.new(supergraph: "app/graphql/supergraph.graphql")
+DashboardQuery = router.parse("query Dashboard { me { username } }")
+DashboardQuery.execute!.me.username
+```
+
+All three modes, tagged and running end to end, are
+[`spec/rspec_spec.rb`](../spec/rspec_spec.rb) — the reference for anything
+this page leaves out.
+
+## Nothing to configure
+
+Each mode works out what to run against, and **refuses — naming what it
+looked for — rather than guessing**:
+
+- **the schema** is `config.schema` if you set one, else the committed dump
+  at `GraphWeaver.schema_path`, else the schema `GraphWeaver.client` talks to.
+  (`config.schema` refuses a federation *subgraph* class: fakes are fabricated
+  against it too, so one subgraph would be a fraction of the graph. A
+  federated graph has no one schema class — that's what `:router` is.)
+- **`:in_process`** needs the live schema *class*, since only that has
+  resolvers: the one your client already runs in-process, else the loaded
+  class that defines everything the schema declares — the same
+  derive-verify-refuse rule that
+  [maps subgraphs](federation.md#which-schema-serves-which-subgraph).
+- **`:router`** plans against the composed supergraph. If your committed dump
+  *is* one (it carries `@join__*` markers), that's it — no config at all. A
+  client can't stand in for it: a client's schema is the API schema the router
+  serves, with the `@join__*` routing table stripped out, so the supergraph has
+  to be named. Subgraphs are derived either way.
+
+So configure only to override a derivation, or to tune fabricated values:
+
+```ruby
+GraphWeaver::Testing.configure do |config|
+  # config.schema = MySchema         # the live class, rather than the dump
+  # config.router = { supergraph: Rails.root.join("supergraph.graphql") }
+  # config.router = { subgraphs: { "reviews" => :fake } }   # either key alone
+  # config.context = { tenant: }     # baseline context every example starts from
+  # config.default_mode = :fake      # what an UNtagged example runs against
+  #                                  # (graphql: false opts one back out)
+  # config.mode = :faker             # or :literal (plain typed values); nil = auto
+  # config.overrides = { "Person.name" => "Daniel" }
+  # config.list_size = 1..3
+  # config.null_chance = 0.1         # nullable fields go nil sometimes
+end
+```
+
+## The context your resolvers see
+
+`graphql_context` is available in every example. It **merges** onto
+`config.context` — the baseline survives unless you override a key — and is
+**reset before the next example**, so one example running as somebody else
+can't leak into the one after it.
+
+Context is setup, so it usually belongs in a `before` block — a group of
+examples sharing one identity says who they are once:
+
+```ruby
+describe "as the owner", graphql: :in_process do
+  before { graphql_context(current_user: alice) }
+
+  it "shows the drafts" do
+    expect(DraftsQuery.execute!.drafts.size).to eq 2
+  end
+
+  it "counts them" do … end
+end
+```
+
+The reset runs ahead of any group hook, so each example re-applies that
+`before` from the same baseline rather than stacking onto the last one's
+context. Set it inline for the one-off:
+
+```ruby
+it "shows the owner's drafts", graphql: :in_process do
+  graphql_context(current_user: alice)
+  expect(DraftsQuery.execute!.drafts.size).to eq 2
+end
+```
+
+Pass a block to scope it, for the example that needs two identities:
+
+```ruby
+graphql_context(admin: true) { expect(SettingsQuery.execute!.settings).to be_present }
+```
 
-person = PersonQuery.execute!(fake, id: "1").person
+Called with nothing it reads the context back. Under `graphql: :fake` it
+refuses: there are no resolvers to receive a context, and silently ignoring
+one would leave an example asserting on data nothing scoped. Pin the data
+itself instead — `graphql_fake(overrides: …)`, below.
+
+## Fabricated data — `graphql: :fake`
+
+`FakeClient` fabricates schema-correct responses for whatever query
+arrives: real enum values, valid `__typename` members, iso8601 date scalars
+— every fake casts cleanly through your generated structs.
+
+```ruby
+fake = GraphWeaver::Testing::FakeClient.new   # schema: falls back to Testing.config
+
+person = PersonQuery.execute!(client: fake, id: "1").person
 person.name       # => "Eliza Kertzmann" (faker-matched on field name, when faker is loaded)
 person.birthday   # => a real Date
 ```
@@ -31,52 +171,120 @@ GraphWeaver::Testing::FakeClient.new(schema:, overrides: {
 })
 ```
 
-With rspec, the setup is two lines in `spec/support/graph_weaver.rb` —
-the require, plus an explicit opt-in to per-example fakes (deliberately
-not a default: silently swapping every example onto a fake would be
-surprising). The schema auto-locates from the committed dump at
-`GraphWeaver.schema_path`:
+Keys are checked against the schema, spellchecked — `"Person.nmae"` raises
+rather than quietly pinning nothing and leaving the example green against
+random data.
+
+### The example that's *about* the data
+
+Fabricated data answers "does this render", not "does it render Ada's two
+orders". `graphql_fake` is the tag with options — same client, built where
+the example can say what it needs:
 
 ```ruby
-require "graph_weaver/rspec"   # seed follows --seed
+it "shows the two paid orders", graphql: :fake do
+  graphql_fake(overrides: {
+    "Reader.name" => "Ada",
+    "Reader.orders" => [{ "status" => "PAID" }, {}],
+  })
 
-GraphWeaver::Testing.configure do |config|
-  config.auto_fake = true              # every example runs against a fresh fake
-  # config.schema = MySchema           # optional: an in-process class instead of the dump
-  # config.mode = :faker               # or :literal (plain typed values); nil = auto
-  # config.overrides = { "Person.name" => "Daniel" }
-  # config.list_size = 1..3
-  # config.null_chance = 0.1           # nullable fields go nil sometimes
+  expect(DashboardQuery.execute!.reader.orders.size).to eq 2
+end
+```
+
+An override pins a **subtree** as readily as a leaf, and **merges**: name
+the fields the example is about and everything else in the selection is
+still fabricated. A pinned list is exactly as long as you write it — `{}`
+means "another one, all fabricated". Inside a subtree the keys are
+*response* keys, as they come back on the wire (`priceCents`, or an alias
+you selected); one the query doesn't select is refused and spellchecked,
+same as a typo'd coordinate. At a union or interface, name the member with
+`"__typename"`.
+
+`graphql_fake` returns the client, which records what it was asked:
+
+```ruby
+fake = graphql_fake
+2.times { Dashboard.load }
+expect(fake.requests.size).to eq 1                      # memoized
+expect(fake.requests.first[:variables]).to eq({ "id" => "1" })
+```
+
+It works in a `before` block, an example body, or a shared context — and
+with no tag at all, since it installs the client itself. The tag is
+`graphql_fake` with no options.
+
+One thing to know: **two identical queries fabricate different data**, so
+assert a memoization with `requests.size`, not by comparing two responses.
+
+### Naming the schema your resolvers run on
+
+`graphql_in_process` is the same idea for real resolvers. The tag runs
+`config.schema` when that's a live class, which is the whole story for an app
+that serves the API it calls:
+
+```ruby
+it "hides another reader's drafts", graphql: :in_process do
+  expect(DraftsQuery.execute!.drafts.map(&:id)).to eq %w[d3]
+end
+```
+
+A federated app has no one live class, so the example says which subgraph it
+means — testing one subgraph's resolvers directly is a different question from
+`graphql: :router`, which plans across the whole graph and stitches. Both are
+worth asking, and a suite asks them of different subgraphs:
+
+```ruby
+it "rejects a review from a blocked reader" do
+  graphql_in_process(Reviews::Schema)
+  …
 end
 ```
 
-With the rspec integration, `rspec --seed 1234` reproduces fake data
-along with test order, and `auto_fake` installs a seeded fake as the
-app client per example (generate modules *without* a baked `client:` so
-they consult `GraphWeaver.client`). `mode:` picks value fabrication: `:faker`
-(semantic, field-name matched — raises if the gem is missing),
-`:literal` (plain type-derived), or nil to auto-detect faker.
+Like `graphql_fake`, it needs no tag, works in a `before` block, and is
+restored after the example. Set the GraphQL context with `graphql_context`
+rather than the helper's `context:` — the helper's is a baseline, and
+`graphql_context` is what merges onto it per example.
+
+`rspec --seed 1234` reproduces fake data along with test order. `config.mode`
+picks value fabrication: `:faker` (semantic, field-name matched — raises if
+the gem is missing), `:literal` (plain type-derived), or nil to auto-detect
+faker.
+
+Need the schema itself inside an example — to sample a field, or build a
+query on the fly? The client in play exposes it as
+`GraphWeaver.client.schema`, and `GraphWeaver::Testing.config.schema` reads
+back what `config.schema =` set, falling back to the committed dump.
 
-Test-only queries don't have to live in `app/` — the conventional paths
-are appendable lists, so the same support file can register a
-spec-local set that `load_generated!` (and the Railtie) pick up:
+Test-only generated modules don't have to live in `app/` — `generated_paths` is
+an appendable list, so a support file can register a spec-local set:
 
 ```ruby
-GraphWeaver.generated_paths << "spec/support/graphql/generated"
-GraphWeaver.queries_paths << "spec/support/graphql/queries"
+# spec/support/graph_weaver.rb
+GraphWeaver.generated_paths << "spec/graphql/generated"
+GraphWeaver.load_generated!   # the appended path needs this call
 ```
 
-**Simulating failures** — every failure mode is just a client, so
+Both lines matter. In Rails the Railtie loads generated modules during boot,
+which is finished before `spec/support/*.rb` runs — so a path appended here is
+never loaded unless you load it. And keep the directory *outside*
+`spec/support/`: rspec-rails requires every `spec/support/**/*.rb` itself, in
+sorted order, so a generated module gets required before the shared `types.rb`
+it needs and dies on `LoadError`.
+
+## Simulating failures
+
+Every failure mode is just a client, so
 error-handling paths are testable without a server that misbehaves on cue:
 
 ```ruby
 Failure = GraphWeaver::Testing::Failure
 
-PersonQuery.execute(id: "1", client: Failure.transport)             # TransportError (cause preserved)
-PersonQuery.execute(id: "1", client: Failure.server(status: 502))   # ServerError
-PersonQuery.execute(id: "1", client: Failure.throttled)             # QueryError, code THROTTLED
-PersonQuery.execute(id: "1", client: Failure.stale_schema)          # schema_stale? => true
-PersonQuery.execute(id: "1", client: Failure.graphql("boom", data: {...}))  # partial failure
+PersonQuery.execute(client: Failure.transport, id: "1")            # TransportError (cause preserved)
+PersonQuery.execute(client: Failure.server(status: 502), id: "1")  # ServerError
+PersonQuery.execute(client: Failure.throttled, id: "1")            # QueryError, code THROTTLED
+PersonQuery.execute(client: Failure.stale_schema, id: "1")         # schema_stale? => true
+PersonQuery.execute(client: Failure.graphql("boom"), id: "1")      # partial failure
 
 # retries: clients run in sequence (the last repeats) — here, two
 # transport failures and then a FakeClient serving good responses
@@ -87,24 +295,63 @@ GraphWeaver::Testing::Sequence.new(Failure.transport, Failure.transport, fake)
 # casting raises GraphWeaver::TypeError (overrides remain the manual escape hatch)
 GraphWeaver::Testing::FakeClient.new(schema:, corrupt: "Person.birthday")
 
-# stale schema naming a real (sampled) field
-Failure.stale_schema(schema: MySchema)
-
 # field-level partial failure with real GraphQL null propagation: the error
 # lands with its concrete path and nulls bubble to the nearest nullable spot
 GraphWeaver::Testing::FakeClient.new(schema:, fail_at: { path: "person.email", code: "PRIVATE" })
 ```
 
-**Capture and replay** — cassettes record real API responses and replay
+## Capture and replay
+
+Cassettes record real API responses and replay
 them offline, above the transport (no HTTP interception):
 
 ```ruby
 # records against the live client when the file is missing, replays after
-cassette = GraphWeaver::Testing::Cassette.use("github", client: live)
+client = GraphWeaver::Testing.cassette("github", client: live)
+```
+
+Re-record with `GRAPHWEAVER_RECORD=1`, and set `config.anonymize = true` so
+real data never lands in a committed file — the full workflow guide is
+**[cassettes](cassettes.md)**.
+
+## Real resolvers, one schema — `graphql: :in_process`
+
+Your actual resolvers, your actual `context`, in the same process — no
+socket, no serialization, and a resolver's real backtrace when it raises.
+
+```ruby
+it "hides other people's drafts", graphql: :in_process do
+  graphql_context(current_user: alice)
+  expect(DraftsQuery.execute!.drafts.map(&:owner)).to all(eq alice.name)
+end
+```
+
+The live schema *class* is found for you (a schema dump has no resolvers,
+so it won't do). If two loaded classes match, or none does, it says so and
+asks for `config.schema = MySchema` — and in Rails, remember that an
+autoloaded schema isn't loaded until something references it.
+
+## A federated graph — `graphql: :router`
+
+Same thing across a federated graph: the tag builds a
+[`Testing::Router`](federation.md#the-local-router), which plans the query
+across your subgraphs and runs it against those **real resolvers** — no
+gateway, no node, no sockets.
+
+```ruby
+describe "the dashboard", graphql: :router do
+  it "stitches a user's reviews" do
+    graphql_context(current_user: user)
+    expect(DashboardQuery.execute!.me.reviews.size).to eq 2
+  end
+end
 ```
 
-Re-record with `GRAPHWEAVER_RECORD=1`, anonymize before committing
-(`config.anonymize = true` scrubs as recordings happen, or
-`rake graph_weaver:cassettes:anonymize` after) — the full workflow guide
-is **[cassettes](cassettes.md)**.
+The router is built once for the suite (parsing a supergraph per example
+would be real time) and installed as `GraphWeaver.client` for each; its
+context is reset from `config.context` every time, so an example that runs
+as someone else can't leak into the next.
 
+What it plans, what it **refuses** and why, how subgraphs are matched to your
+schema classes, and what to do about a supergraph only partly local:
+**[federation → the local router](federation.md#the-local-router)**.