Production-ready subscriptions (SSE + graphql-ws) and a single UTF-8 envelope parser

[ricred]

Summary

Makes the subscription transports (SSE and graphql-ws) production-ready and moves every response path onto a single, allocation-light envelope parser.

No public signature is changed or removed. Several behaviour changes are listed below; please read those first. Full details are in the new CHANGELOG.md ([Unreleased]).

Size note: 35+ files and ~5,000 added lines, ~60% of which are tests. Happy to split this into two PRs (response parser, then subscriptions) if that is easier to review.

Behaviour changes (please review)

• GraphClient.SerializerOptions is a shared, frozen instance: mutating it after construction throws InvalidOperationException.
• __AdditionalProperties is null until first used (no eager dictionary per entity).
• WebSocket: StartAsync no longer awaits the handshake. Connection/ack failures and per-message parse errors surface as OnError on the stream; unknown message types are ignored.
• Empty response body / empty string in ProcessResponseFull(string) / ProcessResponse(string) returns Data = default with no errors instead of throwing JsonException.
• ProcessResponseFull(JsonElement) with a non-object root throws JsonException instead of InvalidOperationException.
• WebSocket close codes follow the graphql-ws reference client (4408 is now retryable). Reconnect is owned by the subscription, with a bounded retry budget (SubscriptionRetryAttempts, default 5), exponential backoff and jitter.

Added

• GraphSubscriptionExecute.StartWithErrorsAsync(): IObservable<GraphResult<T>>, so field errors no longer end the subscription.
• GraphClientOptions: SubscriptionMaxBufferedEvents, SubscriptionOverflowPolicy (Fault / DropOldest / KeepLatest), SubscriptionIdleTimeout (SSE), SubscriptionRetryAttempts (WS).
• QueryExecutor.ProcessResponse(JsonElement, ...) and ProcessResponse(byte[], ...) overloads.

Fixed

• A server complete frame now completes the typed subscription observable.
• A Fault overflow in one subscriber no longer starves the other subscribers.
• SSEClient race between Dispose and connect (possible NRE / spurious failure).
• WSConnectionInitPayload default returns a completed task instead of null.

Single envelope parser: GraphEnvelopeReader

All response paths now parse data / errors / extensions with one internal Utf8JsonReader-based reader (Common/GraphEnvelopeReader): typed queries, GraphClient.ExecuteAsync (GraphQL text, including the non-2xx "is this a GraphQL body?" decision), every ProcessResponse / ProcessResponseFull overload, and subscription payloads.

• CLAUDE.md said QueryExecutor.ProcessResponseFull is "the single place both go through". That rule is kept but now names GraphEnvelopeReader, since that is where the single path lives after this change. @joadan, you wrote that file, so please check the wording.
• EnvelopeAndResponseTests.AllOverloads_ProduceTheSameResult checks that the overloads cannot drift apart again.

Benchmark (BenchmarkDotNet 0.15.8, .NET 10.0.402, in-process, comparing the previous JsonDocument path with the new reader; results checked equal):

Payload	Before (mean / alloc)	After (mean / alloc)
Small	4.04 µs / 3.11 KB	3.51 µs / 2.45 KB
Large (500 items)	8.83 ms / 3,498 KB (Gen2: 156)	8.48 ms / 1,756 KB (Gen2: 0)
Requested field + 2 large sibling root fields	10.21 ms / 6,325 KB	4.97 ms / 19.9 KB

The Large timing is noisy (SD 1.4 ms); the allocation drop is the robust result. Not measured: copying the HTTP body into the buffer.

Testing

• dotnet restore Linq2GraphQL.CI.slnf --locked-mode → build --no-restore (0 warnings, 0 errors) → test --no-build: 446/446 passed
  • on Windows (4 consecutive full runs);
  • on Linux in mcr.microsoft.com/dotnet/sdk:10.0 (a clean clone, same steps as CI's ubuntu job).
• ./scripts/regenerate-test-clients.ps1 -Check: checked-in test clients match the generator.
• New test suites cover SSE framing, idle timeout, WS protocol/close codes/reconnect (in-process graphql-ws and SSE test servers), buffer overflow policies, envelope parsing, and regressions from review.
• Some subscription tests depend on timing. Fixed delays were replaced with waits on the actual condition, and the idle-timeout tests were checked to still fail when the timer re-arm is removed. If one flakes on CI, please tell me.

Notes

• CHANGELOG.md is new in this repo (Keep a Changelog format). Happy to move the notes elsewhere if you prefer.
• Versioning is untouched (Nerdbank.GitVersioning).

[ricred]

@joadan could you take this one? I can't assign or request reviewers from a fork (no triage rights), so a mention will have to do. Happy to split it into smaller PRs if that makes review easier.