feat: prototype Variation E realtime client (standalone RealtimeClient + React hooks)

[pyramation]

Summary

Prototype of "Variation E" (Hybrid) frontend realtime subscription architecture — two new packages that provide a framework-agnostic subscription client and a React hooks layer with React Query cache bridge.

This sits on top of the database-layer realtime infrastructure built in constructive-db PRs #1073–#1086 (partition support, realtime_module, DataRealtime generator, subscriber tables with RLS). The backend is transport-agnostic; this PR demonstrates one possible frontend binding.

@constructive-io/realtime (packages/realtime) — framework-agnostic:

• RealtimeClient wrapping graphql-ws, multiplexing subscriptions over a single WebSocket
• Connection lifecycle management (lazy connect, exponential backoff retry, state listeners)
• createSubscriptionModel() factory for codegen to produce per-table typed .subscribe() methods
• buildSubscriptionDocument() / buildSubscriptionVariables() helpers for codegen templates
• 19 unit tests (graphql-ws mocked)

@constructive-io/react-realtime (packages/react-realtime) — React + React Query:

• RealtimeProvider / useRealtimeClient() context
• useSubscription() hook with optional CacheBridge config (auto-invalidate list queries, optimistic detail cache updates on INSERT/UPDATE, cache removal on DELETE)
• useConnectionState() hook for connection monitoring
• createSubscriptionHook() factory for codegen (generates per-table hooks like useContactSubscription())
• 3 unit tests

Tree-shakeable: each layer imports independently. Escape hatch: use RealtimeClient directly without React hooks.

Review & Testing Checklist for Human

• Architecture review: Verify the two-layer split (standalone client vs React hooks) is the right boundary for codegen. The createSubscriptionHook and createSubscriptionModel factories define the codegen contract — confirm the API shape is what you'd want generated code to call.
• Cache bridge logic (use-subscription.ts applyCacheBridge): This function does setQueryData, invalidateQueries, and removeQueries on React Query cache but has no test coverage. Review the INSERT/UPDATE/DELETE handling for correctness — particularly the getId cast through unknown.
• React hook effect cleanup: useSubscription resubscribes when filterJson (serialized filter) changes. Verify the cleanup/unsubscribe path is correct and doesn't leak subscriptions on rapid filter changes.
• graphql-ws payload parsing (client.ts lines 98–113): The client extracts operation, data, previousValues, timestamp from the GraphQL subscription payload. This assumes a specific payload shape that the Graphile subscription plugin (Phase 3a, not yet built) will need to match.

Notes

• This is a prototype for team discussion, not production code. The goal is to validate the Variation E architecture before building the Graphile subscription plugin and codegen integration.
• React hooks tests are shallow (factory return-type checks only) — no render tests with @testing-library/react. Sufficient for a prototype but would need expansion before shipping.
• The pnpm-lock.yaml diff is large due to formatting changes (pnpm version difference) — the actual new dependency entries are just graphql-ws, @tanstack/react-query, and the workspace link between the two packages.

Link to Devin session: https://app.devin.ai/sessions/19485cf5cc58416a9f86068563d512f5
Requested by: @pyramation

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring