feat: SSR support — lifted onto merged @tanstack/db 0.8.5 (ADR-0011)

[grrowl]

SSR support — dehydrate on the worker, hydrate to the cursor

Upstream shipped: TanStack DB's SSR support merged via PR #1564 and released in @tanstack/db 0.8.0 (DbClient dehydrate()/hydrate(), the exportSyncMeta/importSyncMeta/mergeSyncMeta sync-config hooks — byte-for-byte the signatures our draft-era branch implemented). This PR is the full lift of that work onto released 0.8.5: no vendored tarballs, current main (v0.6.0, ADR-0015–0019 era), and the semantics the merged API actually has. Design + every departure: ADR-0011 (original decision record intact, with a lift Amendments section).

Supersedes #2 (feat/ssr, which tracks the dead draft + vendored builds). Replay source was the completed feat/ssr-rebased port, re-derived commit-by-commit against current main.

What lands

• Server: readSyncSnapshot(req, request) RPC on the Syncable mixin — one consistent {rows, cursor} read over the DO binding, no WebSocket. The required request runs through parseAttachment: one auth gate for the socket and the read path. Cursor is a durable high-water mark (max(currentSeq, drainCursor)); "0" honestly means "no resume point". BLOB values normalize ArrayBuffer → Uint8Array for wire-codec parity (ADR-0017).
• Client: SsrSnapshotTransport (read-only, per-request, swapped at the new structural Transport<Api> seam), syncMeta {v, cursor, where-fingerprint} round-trip with fail-loud-but-safe import/merge, since on first sub, seedCursor (late chunks regress-and-replay via a forced reconnect), always-armed eager snapshot reconcile (authoritative set semantics — no flash-to-empty, no stranded deletes), on-demand transient catch-up with honest truncate for unresumable rows.
• Wire (additive): uptodate gains optional sub (a catch-up's terminal is sub-scoped).
• Merged-API adaptations (the interesting deltas vs the draft — full rationale in the ADR Amendments):
  • exportSyncMeta returns undefined when the adapter holds no claim, via a new Transport.hasPosition seam. Merged upstream consults exportSyncMeta() as "current" on every hydrated chunk; a fresh browser transport exporting {cursor:"0"} would win the MIN-merge against every real dehydrated cursor and silently kill cursor resume. An SSR read at cursor 0 stays a real "no resume point" claim.
  • Adopted 0.8.x contracts: commit() receipts (SyncAppliedReceipt — subset loads settle only once rows are visible), markError (failed first connect fails preload() loud; retried preload recovers), per-subset load rejection, and withCollectionConfigFactory (configs work as collectionOptions(id, …) descriptors with fresh adapter state per DbClient).
  • The regress-reconnect is re-derived against ADR-0016: it is voluntary — bypasses the backoff policy, consumes no attempt, cannot be declared terminal — and the draft's suppressAdvance flag is replaced by receipt-aware socket-identity dispatch (stream frames from an abandoned socket drop and replay; committed/rejected/page still settle their waiters, never the cursor).
• examples/ssr: rebuilt on TanStack Start + the new @tanstack/react-router-with-db — the hand-rolled serverFn/hydrate plumbing is gone; the app-specific part is one transport dependency on the DbClient (snapshot read on the server, WebSocket in the browser) consumed by a shared typed descriptor, zero casts. Two routes: loader-preloaded (rows in the server HTML, socket resumes from the dehydrated cursor) and Suspense-streamed.

Adversarial review

A codex (gpt-5.6-sol) pass over the lift diff found seven real bugs — all fixed, each pinned by a test (commit 227c2aa): negative-cursor validation (would leak the on-demand catch-up sub forever), fingerprint-aware mergeSyncMeta (MIN alone could smuggle foreign-filter rows past import), receipt-aware stale-socket dispatch (a committed mutation must not become a timeout), settlement-gated exportSyncMeta (never claim a boundary whose receipt is unsettled), rejected-receipt-is-failure, on-demand error→ready healing, and a pre-existing ghost-subscription fix (unsubscribe during an in-flight connect).

Verification

• 271 tests green (238 pre-lift + 33 SSR/hardening), including end-to-end dehydrate→hydrate→converge running the real released DbClient on both sides. The full pre-lift suite passes on 0.8.5 unchanged.
• tsc typecheck + package build green; example installs, typechecks, and builds for both client and ssr environments (worker-only modules verified absent from the client bundle).

Notes for review

• Peer dependency moves >=0.6.0 → >=0.8.5 (the hooks shipped in 0.8.0; 0.8.5 carries the receipt contract + descriptor reuse we adopt).
• Documented follow-up, deliberately not in scope: LoadSubsetOptions.signal (cooperative cancellation of shared refcounted subs).
• Ecosystem context: only ElectricSQL implements the syncMeta hooks today — this is the second adapter with true resumable SSR hydration.
• The example builds but has not had a browser pass yet.

🤖 Generated with Claude Code