@ultimat3/realtime 10.0.0 → 11.1.0

package/CLAUDE.md

@@ -27,6 +27,14 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   type-only export leaves no runtime entry). `errors.ts` is deliberately whole on `.`: every code
   reaches the wire through `toWireError`, so a client must be able to name any of them, and the
   module is already in the client graph via `sync-protocol`.
+- **`errors.ts` is the code TABLE plus the client-reachable refusals; two neighbours hold the rest,
+  and every name is still exported from `./errors`** (2026-08-23, at the 500-line ceiling).
+  `realtime-error.ts` holds the base class alone and `replication-errors.ts` the four Postgres ones
+  — the only codes no browser can reach. The base needs its own module rather than a re-export:
+  `extends` runs at module evaluation and imports hoist above it, so a `replication-errors` that
+  imported the base back out of `errors.ts` would read it in its temporal dead zone. Neither
+  neighbour runs anything at import, which is what keeps `sideEffects` naming `errors.ts` alone
+  true — `registerErrorCodes()` stays there, unconditional, and `bun run side-effects` is the check.
 - **`sideEffects` is the ARRAY `["./src/errors.ts"]`, never `false` and never absent.** Absent was
   what made the failure above unrecoverable — with no field a bundler must assume every module has
   effects, so nothing was tree-shaken and `nats` came along with `useLive`. Measured, not guessed:
@@ -205,6 +213,17 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   other node renders for a full TTL. During a **rolling restart** that is every room showing each
   user twice for up to 30s, beside the same client's reconnection under a new socket id. One
   `evict(socket, code, reason)`, and every path that ends a socket without a callback takes it.
+- **A `drain()` WAITS for the presence leaves it started; a `close` callback cannot** (2026-08-23).
+  `teardown` returns those promises as well as `detach`ing them: Bun's `close` callback is
+  synchronous, so there the detach is the whole of it — but a drain has no callback behind it and
+  is the one path that can wait. It did not: `release()`, `hub.close()` and the process's exit all
+  ran under N·M in-flight KV writes, so every other node rendered every drained member for a full
+  TTL — the same rolling-restart double vision `evict` exists to prevent, reached the long way
+  round. `evictInChunks` (`drain-evictions.ts`) evicts `DRAIN_EVICT_CHUNK` sockets, waits out what
+  they started, then takes the next: one synchronous loop over 50,000 sockets opens a quarter of a
+  million writes on one connection at the exact moment the fleet is already restarting.
+  `allSettled`, never `all` — a leave that fails is a member left to its TTL, which is what the
+  write meant when nobody waited for it at all, and it must not hold up the sockets behind it.
 - **The idle sweep exists, is armed by `start()`, and its budget is an APPLICATION one.**
   `SocketRegistry.sweepIdle` had no caller for as long as it existed, so `touch()`, `idleFor` and
   the 120s default decided nothing and `idleTimeoutMs` was unreachable from `createSyncNode`. The
@@ -325,6 +344,38 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - One registered `LiveClient` per app (`setLiveClient`), and every hook reads it through that seam —
   no hook takes a client argument, and an unregistered one is `X_LIVE_CLIENT_MISSING`, never a
   lazily-constructed default.
+- **A DOM is the whole of the question, and it decides what "no client" MEANS** (2026-08-23, issue
+  #271). Deliberately the same rule, the same probe and the same words as `@ultimat3/ui`'s
+  `solid()`: with a DOM, a hook that finds no registration is a real bug — the app entry forgot
+  `setLiveClient` and every live query on the page is dead — so it stays `X_LIVE_CLIENT_MISSING`.
+  Without one there is no socket a client could have been registered *for*; that is a **server
+  render**, and it gets `serverRenderLiveClient()`. Before it, a page whose whole body read a live
+  query could not server-render at all: `useConnection()` threw and the route answered 500, and the
+  existing `hasLiveClient()` guard could not help — it only serves a component that already has a
+  static fallback written. `hasLiveClient()` still answers **false** on the server, on purpose,
+  because that is exactly what such a component is asking.
+- **The server client serves the first render and opens no socket, so it holds nothing per
+  request.** One instance per process, and that is only safe because `useLive` on it registers
+  nothing: a client that kept a registration per call would grow by one entry per request forever
+  and pin a row window with each. `state()` is **`loading`**, never `offline` and never `live` — the
+  rows arrive over a socket this render does not have, so the page's own loading fallback is what
+  the document carries. `offline` would be read as a settled answer (`state() !== 'loading'` is the
+  gate a page writes), so an empty result set would render "you have no posts" for a feed that has
+  some. `connected` is `true` for the mirror-image reason: `useConnection().offline` is a banner
+  about this visitor's connectivity, and the request being served is the proof it is up. Everything
+  that can only mean "talk to the socket" — `mutate`, `drain` — refuses with
+  `X_LIVE_SERVER_RENDER`, because a dropped mutation looks exactly like one that happened.
+- **The hook seam takes `LiveClientLike`, not the `LiveClient` class, and that is a measurement.**
+  A value import of the class from `hooks.ts` put the whole connection lifecycle — heartbeat, topic
+  book, mutation sender, wire protocol, backoff — into every island that calls `useLive`: a
+  `useLive`-only browser chunk went **8,368 B → 26,571 B**. Against the structural shape it is
+  9,356 B, and the ~1 kB is the server client and its refusal. `type-pins.ts`
+  (`_LiveClientSatisfiesTheHookSeam`) is what keeps the two in step.
+- **A server render that renders is not a live page.** A page component never runs in a browser —
+  only an `island()` module does — so `useLive` in a page body server-renders its loading branch and
+  nothing replaces it unless that route ships an island that registers a client. The server client
+  removes the 500; it does not make a page live, and it must never be described as if it did.
+  `examples/dummy`'s `/feed` is exactly that state and its own header says so.
 - Anything a component reads is a **getter or an accessor**, never a value snapshotted at hook time:
   a plain field cannot re-render. `MutatorLike.local` is declared with method syntax so an
   `@ultimat3/action` `Mutator` assigns with no cast — a function-typed property would not.
@@ -547,12 +598,20 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   what releases the change subscription carrying them. `drain()` + `stop()` are the `close` phase.
   Registered with no phase, both landed in `close` and the node upgraded new websockets until the
   very end. `listenSyncNode` unregisters both on `stop()`.
-- **Readiness is asked twice, because `authenticate` is app code with an await in it.** A request
-  that passed the check at the top of `handleUpgrade` can be parked in a token service when SIGTERM
-  lands, and the `accept` phase is over by the time it reaches `server.upgrade` — one more socket on
-  a node the load balancer has already stopped routing to, so nothing takes it over. `ready` and the
-  socket count are therefore **functions** on `UpgradeDeps`, not values read once. The recheck sheds
-  with the same 503 + `retry-after-ms` and takes no second `tryAccept()`: that budget was spent.
+- **Readiness AND the connection cap are asked twice, because `authenticate` is app code with an
+  await in it.** A request that passed the checks at the top of `handleUpgrade` can be parked in a
+  token service when SIGTERM lands, and the `accept` phase is over by the time it reaches
+  `server.upgrade` — one more socket on a node the load balancer has already stopped routing to, so
+  nothing takes it over. `ready` and the socket count are therefore **functions** on `UpgradeDeps`,
+  not values read once.
+  **`socketCount()` was the half that was read once and never re-asked** (2026-08-23), which is the
+  same staleness with a worse blast radius: a restart storm dials every client of a dead node at
+  this one at once and each parks in the token service having passed the cap while the node still
+  held nothing, so `maxConnections: 2` with ten parked upgrades took **ten** sockets — reproduced,
+  `upgraded 10, shed 0`. Sound because there is no await between the recheck and `server.upgrade`,
+  and the count moves INSIDE it: Bun runs `websocket.open` synchronously there, which is where
+  `sockets.add` runs. The recheck sheds with the same 503 + `retry-after-ms` and takes no second
+  `tryAccept()`: that budget was spent.
 - **A client `send` that returned is not an acknowledgement.** A browser `WebSocket.send` on a
   CLOSING socket discards the frame and returns normally, so a drained mutation is `inflight` until
   the server settles it or `requeueInflight` returns it. Only `pending` is sendable, `drain()` is one
@@ -714,6 +773,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 | `sync-frames.ts` | what a RECEIVED frame does to server state — the node's inbound surface, and the mirror of `client-frames.ts` |
 | `sync-upgrade.ts` | the node's HTTP surface: `/healthz`, `/readyz`, load shedding, and the authenticated upgrade — `WsData` and `UpgradeTarget` are declared with the decision that builds them |
 | `sync-listen.ts` | binding a node to `Bun.serve` and to the shutdown hook — the only `Bun.serve` in the package |
+| `drain-evictions.ts` | evicting every socket a drain holds, in bounded chunks, and waiting out the presence leaves each eviction started |
 | `query-window.ts` | the shared pre-policy window per query id: built once, read once for N subscribers, and replaced when it is known to be wrong |
 | `client-frames.ts` | what a RECEIVED frame does to client state, and `ClientFrameTarget` — the only inbound surface the client exposes. The mirror of `sync-frames.ts` |
 | `client-harness-fixture.ts` | the injected socket + scheduler + harness both client suites drive. Excluded from the tarball |

package/README.md

@@ -81,13 +81,23 @@ Client names — `useLive`, `liveHookFor`, `LiveClient`, `OfflineQueue`, `Rebase
 | wire | `.` | `PROTOCOL_VERSION`, `encode`, `decode`, `Frame` |
 | halves | both | `LiveClient` on `.`; `createSyncNode` / `listenSyncNode` (`sync` role) on `./server` |
 | a socket's identity | `./server` | `SyncAuthenticator`, `SyncGrant`, `GrantBook`, `sweepGrants`, `DEFAULT_REAUTH_INTERVAL_MS` |
-| hooks | `.` | `setLiveClient`, `useLive`, `useConnection`, `useMutation`, `useMutationQueue` |
+| hooks | `.` | `setLiveClient`, `useLive`, `useConnection`, `useMutation`, `useMutationQueue`, `hasLiveClient` |
+| the server render's client | `.` | `serverRenderLiveClient` — what a hook falls back to with no DOM; `LiveClientLike` is the shape both it and `LiveClient` satisfy |
 | the typed projection | `.` | `liveHookFor` — one query bound to one named hook |
 
 ## The four hooks
 
 Register the client once, in the app entry. Every hook reads it from there — no hook takes a client
-argument, and one that runs before the registration is `X_LIVE_CLIENT_MISSING`, never a default.
+argument, and one that runs **in a browser** before the registration is `X_LIVE_CLIENT_MISSING`,
+never a default.
+
+**A server render is not a missing registration.** With no DOM there is no socket a client could
+have been registered for, so every hook falls back to `serverRenderLiveClient()`: `useLive` answers
+`state() === 'loading'` with no rows, `useConnection()` reports online, both queue counts are `0`,
+and `mutate` / `drain` refuse with `X_LIVE_SERVER_RENDER`. The page renders its own loading branch
+and a hydrating island takes over. `hasLiveClient()` still answers `false` there, which is what a
+component with a static fallback is asking. `useLive` in a page BODY is not made live by this — a
+page component never runs in a browser; put the live half in an `island()`.
 
 ```ts
 setLiveClient(new LiveClient({ signal: createSignal, connect, buildId, store, queue }));
@@ -203,6 +213,9 @@ back in a `finally`, and releasing twice is a no-op.
 
 The accept budget bounds the accept **rate**; `maxConnections` bounds the **count**, and they are
 two different attacks — 500 accepts/s held open with one keepalive each is 1.8M sockets an hour.
+Both the count and `/readyz` are re-asked **after** `authenticate` resolves and immediately before
+`server.upgrade`: awaiting app code is awaiting a token service, and a restart storm parks every
+client of a dead node in there at once, each having passed a cap the node has since filled.
 The frame budget is per socket and checked at the top of the frame router, before anything a frame
 can reach: a subscribe frame is a database read, a presence write and a fleet-wide publish, and one
 authenticated socket is the cheapest foothold there is.
@@ -412,6 +425,11 @@ wire twice by a reconnect that raced an ack.
   keeps its patch stream**. The `close` phase is `drain()` then `stop()`. Registered with no phase it
   all landed in `close`, and until that ran the node went on upgrading new websockets onto a process
   that was going away. Both hooks are unregistered by the listener's `stop()`.
+- **`drain()` resolves once the presence leaves have LANDED**, not once they have been started —
+  in bounded chunks of sockets, so a node holding tens of thousands does not open a write per topic
+  per socket in one go. Started and not waited for, the process could exit with them still on the
+  wire, and every other node would render every drained member for a full TTL: the rolling-restart
+  double vision the leave exists to prevent.
 - **A full presence frame is capped** at `maxMembers` (256) and carries `total`, so a 5,000-person
   room renders "and 4,744 others" instead of shipping 5,000 members to every joiner. The set itself
   is never capped — the sweep differences it — and one node per topic runs that sweep, elected
@@ -523,7 +541,8 @@ wire twice by a reconnect that raced an ack.
 `X_PROTOCOL_VERSION` · `X_CURSOR_STALE` ·
 `X_REBASE_CONFLICT` · `X_TRANSPORT_UNAVAILABLE` · `X_TRANSPORT_PROTOCOL` ·
 `X_REPLICATION_FAILED` · `X_REPLICATION_PROTOCOL` · `X_REPLICATOR_SLOT_HELD` ·
-`X_LIVE_CLIENT_MISSING` · `X_LIVE_QUERY_UNKNOWN` · `X_LIVE_REPLICA_IDENTITY` ·
+`X_LIVE_CLIENT_MISSING` · `X_LIVE_SERVER_RENDER` · `X_LIVE_QUERY_UNKNOWN` ·
+`X_LIVE_REPLICA_IDENTITY` ·
 `X_SOCKET_UNAUTHENTICATED` · `X_SOCKET_AUTH_UNAVAILABLE` · `X_NOT_IMPLEMENTED`
 
 Topics deny by default: a topic with no matching guard is forbidden. An authz hole is not a config

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "10.0.0",
+  "version": "11.1.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
@@ -36,8 +36,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "10.0.0",
-    "@ultimat3/query": "10.0.0",
+    "@ultimat3/core": "11.1.0",
+    "@ultimat3/query": "11.1.0",
     "nats": "2.29.3"
   }
 }

package/src/client-contract.ts

@@ -55,6 +55,29 @@ export interface MutatorRef<T extends TableMap = TableMap> {
   readonly conflict?: ConflictStrategy;
 }
 
+/**
+ * What the HOOKS need a client to be — every member `hooks.ts` reads, and not one more.
+ *
+ * A structural interface rather than the `LiveClient` class, and the reason is measured: a value
+ * import of that class from the hook seam put the whole connection lifecycle (heartbeat, topic
+ * book, mutation sender, wire protocol, backoff) into every island that calls `useLive`, taking a
+ * `useLive`-only browser chunk from 8,368 B to 26,571 B. The server render's client
+ * (`server-render-client.ts`) satisfies this and imports no lifecycle at all, so the browser pays
+ * nothing for a shape only the server uses. `type-pins.ts` pins that `LiveClient` still satisfies
+ * it, so a member added there and not here is a build error rather than a hook that cannot see it.
+ */
+export interface LiveClientLike<T extends TableMap = TableMap> {
+  readonly signal: SignalFactory;
+  readonly queue: OfflineQueue | undefined;
+  readonly connected: boolean;
+  readonly reconnectAt: () => number | null;
+  readonly appUpdateAvailable: () => string | null;
+  useLive<R extends Row>(query: LiveQueryRef, input: JsonValue): LiveHandle<R>;
+  mutate(mutator: MutatorRef<T>, input: JsonValue, key?: string): Promise<void>;
+  drain(): Promise<void>;
+  onQueueChange(listener: () => void): () => void;
+}
+
 export interface LiveClientOptions<T extends TableMap = TableMap> {
   readonly signal: SignalFactory;
   /** Called for every connect attempt; returning a fresh socket keeps reconnect logic here. */

package/src/client.ts

@@ -33,6 +33,7 @@ import { backoffDelay, defaultBackoff, timeoutScheduler } from './thundering-her
  */
 export type {
   ClientSocket,
+  LiveClientLike,
   LiveClientOptions,
   LiveHandle,
   LiveQueryRef,

package/src/drain-evictions.ts

@@ -0,0 +1,31 @@
+// Evicting every socket a drain holds, in bounded chunks, and waiting out what each eviction put
+// on the bus. Split out of `sync-node.ts` at the 500-line ceiling; the loop closes over nothing the
+// node holds, which is the same seam `detach.ts` took.
+
+/** Sockets evicted before the leaves they started are awaited. See `evictInChunks`. */
+export const DRAIN_EVICT_CHUNK = 128;
+
+/**
+ * Every socket released, then the writes those releases started, then the next chunk.
+ *
+ * Chunked rather than one pass, because an eviction's presence leave is a write per TOPIC per
+ * SOCKET: a node holding 50,000 sockets in a handful of rooms each would open a quarter of a
+ * million KV writes on one connection in a single synchronous loop, which is a self-inflicted
+ * thundering herd on the bus at the exact moment the fleet is already restarting.
+ *
+ * `allSettled`, never `all`: a leave that fails is a member left to its TTL — the same degradation
+ * the write has when nobody waits for it at all — and it must not stop the sockets behind it from
+ * being released. The failure itself is already reported, by the `detach` the eviction path
+ * attached before handing the promise back here.
+ */
+export async function evictInChunks<Socket>(
+  sockets: readonly Socket[],
+  evict: (socket: Socket) => readonly Promise<unknown>[],
+  chunkSize: number = DRAIN_EVICT_CHUNK,
+): Promise<void> {
+  for (let start = 0; start < sockets.length; start += chunkSize) {
+    const pending: Promise<unknown>[] = [];
+    for (const socket of sockets.slice(start, start + chunkSize)) pending.push(...evict(socket));
+    await Promise.allSettled(pending);
+  }
+}

package/src/errors.ts

@@ -1,7 +1,8 @@
 // Realtime's X_* codes. Every throw in this package goes through one of these classes so
 // the same string renders in the terminal, the browser overlay, and `--json`.
 
-import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+import { registerErrorCodes } from '@ultimat3/core';
+import { RealtimeError } from './realtime-error';
 
 /** Codes this package declares and owns. */
 export const REALTIME_OWNED_ERROR_CODES = [
@@ -18,6 +19,7 @@ export const REALTIME_OWNED_ERROR_CODES = [
   'X_REPLICATION_FAILED',
   'X_REPLICATOR_SLOT_HELD',
   'X_LIVE_CLIENT_MISSING',
+  'X_LIVE_SERVER_RENDER',
   'X_LIVE_ROW_UNIDENTIFIED',
   'X_LIVE_QUERY_UNKNOWN',
   'X_LIVE_REPLICA_IDENTITY',
@@ -111,7 +113,8 @@ export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, stri
   X_REPLICATION_PROTOCOL: 'the WAL stream cannot be decoded',
   X_REPLICATION_FAILED: 'the replication connection was refused',
   X_REPLICATOR_SLOT_HELD: 'another replicator already owns this database',
-  X_LIVE_CLIENT_MISSING: 'a realtime hook ran with no LiveClient registered',
+  X_LIVE_CLIENT_MISSING: 'a realtime hook ran in a browser with no LiveClient registered',
+  X_LIVE_SERVER_RENDER: 'a browser-only live operation ran during a server render',
   X_LIVE_ROW_UNIDENTIFIED: 'a live query returned a row with no id',
   X_LIVE_QUERY_UNKNOWN: 'no live query is registered under the name a subscribe frame asked for',
   X_LIVE_REPLICA_IDENTITY: 'a replicated table sends a key-only row on delete',
@@ -128,23 +131,17 @@ registerErrorCodes(
   ),
 );
 
-/**
- * Base for every realtime error. No `docs:` — `UltimateError` fills it from
- * `describeErrorCode(code).docs`, which is `@ultimat3/core`'s `ERROR_DOCS_URL`: one page for every
- * code, never one per code, because `wiki/` is the framework's only public documentation surface
- * and a code lives there in a TABLE ROW, which has no anchor. The
- * `https://ultimate.dev/errors/<code>` links this class built until 9.x answered 404, host
- * included, on every error it has ever thrown — including the ones `toWireError` puts on the wire.
- */
-export class RealtimeError extends UltimateError {
-  constructor(opts: { code: RealtimeErrorCode; cause: string; fix: string }) {
-    super({
-      code: opts.code,
-      cause: opts.cause,
-      fix: opts.fix,
-    });
-  }
-}
+// Re-exported, never re-declared: `RealtimeError` lives in `realtime-error.ts` and the four
+// replication errors in `replication-errors.ts`, so this file stays the CODE TABLE plus the
+// client-reachable refusals. Every name is still importable from `./errors`, which is what the
+// seventeen `pg-*` modules and the barrel already do.
+export { RealtimeError } from './realtime-error';
+export {
+  ReplicaIdentityError,
+  ReplicationFailedError,
+  ReplicationProtocolError,
+  ReplicatorSlotHeldError,
+} from './replication-errors';
 
 /** Subscribe (or an actor change) denied by the topic's policy. Never leaks the topic's data. */
 export class TopicForbiddenError extends RealtimeError {
@@ -284,93 +281,39 @@ export class TransportProtocolError extends RealtimeError {
 }
 
 /**
- * The bytes on the replication socket are not the bytes the protocol allows: a truncated message,
- * an unknown pgoutput tag, an auth method we do not speak. Always a version or configuration
- * mismatch rather than a transient fault, so retrying the same connection cannot help.
- */
-export class ReplicationProtocolError extends RealtimeError {
-  constructor(args: { stage: string; detail: string; fix?: string }) {
-    super({
-      code: 'X_REPLICATION_PROTOCOL',
-      cause: `postgres replication ${args.stage}: ${args.detail}`,
-      fix:
-        args.fix ??
-        'x doctor db — the server must be postgres >= 14 with a pgoutput publication and wal_level=logical',
-    });
-  }
-}
-
-/**
- * The replication connection itself failed — refused credentials, a slot another process holds,
- * an `ErrorResponse` from the server. The server's own message is passed through verbatim
- * because it names the object that has to change.
- */
-export class ReplicationFailedError extends RealtimeError {
-  constructor(args: { stage: string; detail: string; fix: string }) {
-    super({
-      code: 'X_REPLICATION_FAILED',
-      cause: `postgres replication ${args.stage} failed: ${args.detail}`,
-      fix: args.fix,
-    });
-  }
-}
-
-/**
- * A second replicator found the advisory lock held. Distinct from `X_REPLICATION_FAILED` because
- * nothing is wrong with this process: the database already has its one replicator, and a second
- * one that started anyway would publish every change twice. Terminal for a container whose whole
- * job is that role — the scheduler is the thing that has to change, not the connection.
- */
-export class ReplicatorSlotHeldError extends RealtimeError {
-  constructor(args: { key: string; holder?: string | undefined }) {
-    super({
-      code: 'X_REPLICATOR_SLOT_HELD',
-      cause:
-        `advisory lock ${args.key} is held${args.holder === undefined ? '' : ` by ${args.holder}`}` +
-        ' — one database has exactly one replicator',
-      fix: 'scale the replicator to 1 per database: kubectl scale deploy/replicator --replicas=1',
-    });
-  }
-}
-
-/**
- * A table in the entity list replicates with a replica identity other than FULL, so its `delete`
- * (and any key-changing `update`) carries the KEY COLUMNS ONLY. `toRow` accepts that tuple —
- * it only requires a text `id` — so the live matcher decides "did this row leave the result set"
- * from a one-column row, and a row policy written against `!row.private` reads `undefined`.
+ * A hook was called IN A BROWSER before the app entry registered its client. Never a transient
+ * fault: the registration is a single call in the entry, so the fix is the call itself rather than
+ * a retry.
  *
- * **Raised at preflight and LOGGED, never thrown.** Every app running today on the default
- * identity would stop booting, and the replicator refusing to start is a worse outcome than the
- * partial rows it is warning about. The runtime half is `ReplicationStreamStats.partialBefore`,
- * which counts the changes this actually affects. Refusing it at `x verify` time is the follow-up.
- *
- * The tables are named because the fix is per table, and they are the entity list's own names —
- * every one has already passed `assertIdentifier`, so the `fix:` is SQL that can be pasted.
+ * A server render is deliberately not this error, and never was a missing registration: there is
+ * no socket to register a client for. It gets `serverRenderLiveClient()` instead — the same rule
+ * `@ultimat3/ui`'s `solid()` follows for a missing Solid runtime, one package over.
  */
-export class ReplicaIdentityError extends RealtimeError {
-  constructor(args: { tables: readonly string[] }) {
+export class LiveClientMissingError extends RealtimeError {
+  constructor(args: { hook: string }) {
     super({
-      code: 'X_LIVE_REPLICA_IDENTITY',
-      cause:
-        `${args.tables.join(', ')} replicate with a replica identity other than FULL, so a ` +
-        'delete carries the key columns only and a live query decides visibility from a partial row',
-      fix:
-        `${args.tables.map((table) => `ALTER TABLE ${table} REPLICA IDENTITY FULL;`).join(' ')}` +
-        ' -- rows already written to the WAL keep the identity they were written with',
+      code: 'X_LIVE_CLIENT_MISSING',
+      cause: `${args.hook}() ran in a browser before any LiveClient was registered`,
+      fix: 'setLiveClient(new LiveClient({ signal: createSignal, connect, buildId })) in the app entry, above the first render',
     });
   }
 }
 
 /**
- * A hook was called before the app entry registered its client. Never a transient fault: the
- * registration is a single call in the entry, so the fix is the call itself rather than a retry.
+ * Something that can only mean "talk to the socket" ran on the server client — a mutation, a
+ * publish, a topic subscription, a dial. There is no socket during a server render and there never
+ * will be one: the document is built and sent, and the browser opens the connection.
+ *
+ * A refusal rather than a silent no-op, because both alternatives are worse. Queueing it would
+ * hold one process-wide queue on behalf of whichever request happened to render, and dropping it
+ * would make a write that never happened look like one that did.
  */
-export class LiveClientMissingError extends RealtimeError {
-  constructor(args: { hook: string }) {
+export class ServerRenderLiveError extends RealtimeError {
+  constructor(args: { operation: string }) {
     super({
-      code: 'X_LIVE_CLIENT_MISSING',
-      cause: `${args.hook}() ran before any LiveClient was registered`,
-      fix: 'setLiveClient(new LiveClient({ signal: createSignal, connect, buildId })) in the app entry, above the first render',
+      code: 'X_LIVE_SERVER_RENDER',
+      cause: `${args.operation} ran during a server render, where this app has no live socket`,
+      fix: 'call it from an island mount() instead of from the page — or guard it with hasLiveClient(), which answers false on the server',
     });
   }
 }

package/src/hooks.ts

@@ -3,15 +3,16 @@
 // accessor is a closure over the `SignalFactory` the registered `LiveClient` was built with, and
 // every hook resolves that client through one ambient seam rather than a context per surface.
 
-import type { LiveClient, LiveHandle, LiveQueryRef, MutatorRef } from './client';
+import type { LiveClientLike, LiveHandle, LiveQueryRef, MutatorRef } from './client';
 import { LiveClientMissingError } from './errors';
 import type { JsonValue, Row } from './json';
 import type { LocalTx } from './local-store';
 import type { ConflictStrategy } from './rebase';
+import { serverRenderLiveClient } from './server-render-client';
 
 /** What `setLiveClient` holds. The version signal is the queue's only reactive handle — see below. */
 interface Registered {
-  readonly client: LiveClient;
+  readonly client: LiveClientLike;
   /** Read to subscribe, bumped to invalidate: `OfflineQueue` stores plain arrays, not signals. */
   readonly version: () => number;
   readonly bump: () => void;
@@ -22,7 +23,7 @@ interface Registered {
 let registered: Registered | null = null;
 
 /** Register once, in the app entry, before the first render. One app, one socket, one client. */
-export function setLiveClient(client: LiveClient): void {
+export function setLiveClient(client: LiveClientLike): void {
   // The previous registration's listener goes with it. The client outlives `setLiveClient` — a hot
   // reload, a test's next case, an app that re-registers after signing in — so a discarded
   // unsubscribe is a listener nothing can reach, bumping a signal nothing renders, once per
@@ -50,9 +51,41 @@ export function hasLiveClient(): boolean {
   return registered !== null;
 }
 
+/**
+ * A DOM is the whole of the question — the same probe and the same rule `@ultimat3/ui`'s `solid()`
+ * follows, and deliberately the same words. With a DOM, a hook reaching for a client nobody
+ * registered is a real bug: the app entry forgot `setLiveClient`, and every live query on the page
+ * is dead. Without one there is no socket a client could have been registered FOR — that is a
+ * server render, and `serverRenderLiveClient()` is an honest account of it rather than a
+ * degradation of a working path. Never widen this to "no client, never throw": that is the silent
+ * feed-that-never-loads the split exists to prevent.
+ */
+function hasDom(): boolean {
+  return typeof document !== 'undefined' && typeof window !== 'undefined';
+}
+
+/**
+ * The server render's registration, built once. Deliberately NOT written to `registered`:
+ * `hasLiveClient()` must keep answering `false` on the server, because that is the guard a
+ * component with a static fallback already uses to decide it is being server-rendered
+ * (`examples/dummy`'s `update-banner.tsx`).
+ */
+let serverSide: Registered | null = null;
+
+function serverRegistration(): Registered {
+  if (serverSide !== null) return serverSide;
+  const client = serverRenderLiveClient();
+  // The version signal never moves, and nothing on the server can move it: one pass, no queue,
+  // no ack — so `bump` and `release` are the no-ops that fact makes them.
+  const [version] = client.signal<number>(0);
+  serverSide = { client, version, bump: () => undefined, release: () => undefined };
+  return serverSide;
+}
+
 function live(hook: string): Registered {
-  if (registered === null) throw new LiveClientMissingError({ hook });
-  return registered;
+  if (registered !== null) return registered;
+  if (hasDom()) throw new LiveClientMissingError({ hook });
+  return serverRegistration();
 }
 
 // ---- useLive ------------------------------------------------------------------------------------

package/src/index.ts

@@ -9,6 +9,7 @@ export { applyPatches, orderAfterPatches } from './apply-patches';
 export {
   type ClientSocket,
   LiveClient,
+  type LiveClientLike,
   type LiveClientOptions,
   type LiveHandle,
   type LiveQueryRef,
@@ -54,6 +55,7 @@ export {
   ReplicationFailedError,
   ReplicationProtocolError,
   ReplicatorSlotHeldError,
+  ServerRenderLiveError,
   SubscriptionLimitError,
   TopicForbiddenError,
   TransportProtocolError,
@@ -139,6 +141,8 @@ export {
   type ServerAck,
   strategyName,
 } from './rebase';
+// ---- what a LiveClient IS on the server: it serves the first render and opens no socket --------
+export { serverRenderLiveClient } from './server-render-client';
 // ---- the wire -------------------------------------------------------------------------------------
 export {
   type AckFrame,

package/src/realtime-error.ts

@@ -0,0 +1,28 @@
+// The class every realtime error extends, and nothing else.
+//
+// Apart from `errors.ts` so a concern-specific error module can extend it WITHOUT importing the
+// code table — `errors.ts` re-exports both, so `RealtimeError` and every subclass stay importable
+// from where they always were. Its own file rather than a re-export inside `errors.ts`, because
+// that would be a cycle: `extends` runs at module evaluation, imports hoist above it, and the base
+// would be in its temporal dead zone by the time the subclass module was evaluated.
+
+import { UltimateError } from '@ultimat3/core';
+import type { RealtimeErrorCode } from './errors';
+
+/**
+ * Base for every realtime error. No `docs:` — `UltimateError` fills it from
+ * `describeErrorCode(code).docs`, which is `@ultimat3/core`'s `ERROR_DOCS_URL`: one page for every
+ * code, never one per code, because `wiki/` is the framework's only public documentation surface
+ * and a code lives there in a TABLE ROW, which has no anchor. The
+ * `https://ultimate.dev/errors/<code>` links this class built until 9.x answered 404, host
+ * included, on every error it has ever thrown — including the ones `toWireError` puts on the wire.
+ */
+export class RealtimeError extends UltimateError {
+  constructor(opts: { code: RealtimeErrorCode; cause: string; fix: string }) {
+    super({
+      code: opts.code,
+      cause: opts.cause,
+      fix: opts.fix,
+    });
+  }
+}

package/src/replication-errors.ts

@@ -0,0 +1,87 @@
+// The four refusals the Postgres replication half raises: the wire, the connection, the slot, and
+// the replica identity it warns about.
+//
+// Split out of `errors.ts` on the one seam this package already draws — these are the only codes
+// no browser can reach, thrown by `pg-*.ts` and the replicator and by nothing on the client half.
+// The codes themselves stay in `errors.ts`, whose `registerErrorCodes()` is what
+// `package.json`'s `sideEffects` names; this module runs nothing at import.
+
+import { RealtimeError } from './realtime-error';
+
+/**
+ * The bytes on the replication socket are not the bytes the protocol allows: a truncated message,
+ * an unknown pgoutput tag, an auth method we do not speak. Always a version or configuration
+ * mismatch rather than a transient fault, so retrying the same connection cannot help.
+ */
+export class ReplicationProtocolError extends RealtimeError {
+  constructor(args: { stage: string; detail: string; fix?: string }) {
+    super({
+      code: 'X_REPLICATION_PROTOCOL',
+      cause: `postgres replication ${args.stage}: ${args.detail}`,
+      fix:
+        args.fix ??
+        'x doctor db — the server must be postgres >= 14 with a pgoutput publication and wal_level=logical',
+    });
+  }
+}
+
+/**
+ * The replication connection itself failed — refused credentials, a slot another process holds,
+ * an `ErrorResponse` from the server. The server's own message is passed through verbatim
+ * because it names the object that has to change.
+ */
+export class ReplicationFailedError extends RealtimeError {
+  constructor(args: { stage: string; detail: string; fix: string }) {
+    super({
+      code: 'X_REPLICATION_FAILED',
+      cause: `postgres replication ${args.stage} failed: ${args.detail}`,
+      fix: args.fix,
+    });
+  }
+}
+
+/**
+ * A second replicator found the advisory lock held. Distinct from `X_REPLICATION_FAILED` because
+ * nothing is wrong with this process: the database already has its one replicator, and a second
+ * one that started anyway would publish every change twice. Terminal for a container whose whole
+ * job is that role — the scheduler is the thing that has to change, not the connection.
+ */
+export class ReplicatorSlotHeldError extends RealtimeError {
+  constructor(args: { key: string; holder?: string | undefined }) {
+    super({
+      code: 'X_REPLICATOR_SLOT_HELD',
+      cause:
+        `advisory lock ${args.key} is held${args.holder === undefined ? '' : ` by ${args.holder}`}` +
+        ' — one database has exactly one replicator',
+      fix: 'scale the replicator to 1 per database: kubectl scale deploy/replicator --replicas=1',
+    });
+  }
+}
+
+/**
+ * A table in the entity list replicates with a replica identity other than FULL, so its `delete`
+ * (and any key-changing `update`) carries the KEY COLUMNS ONLY. `toRow` accepts that tuple —
+ * it only requires a text `id` — so the live matcher decides "did this row leave the result set"
+ * from a one-column row, and a row policy written against `!row.private` reads `undefined`.
+ *
+ * **Raised at preflight and LOGGED, never thrown.** Every app running today on the default
+ * identity would stop booting, and the replicator refusing to start is a worse outcome than the
+ * partial rows it is warning about. The runtime half is `ReplicationStreamStats.partialBefore`,
+ * which counts the changes this actually affects. Refusing it at `x verify` time is the follow-up.
+ *
+ * The tables are named because the fix is per table, and they are the entity list's own names —
+ * every one has already passed `assertIdentifier`, so the `fix:` is SQL that can be pasted.
+ */
+export class ReplicaIdentityError extends RealtimeError {
+  constructor(args: { tables: readonly string[] }) {
+    super({
+      code: 'X_LIVE_REPLICA_IDENTITY',
+      cause:
+        `${args.tables.join(', ')} replicate with a replica identity other than FULL, so a ` +
+        'delete carries the key columns only and a live query decides visibility from a partial row',
+      fix:
+        `${args.tables.map((table) => `ALTER TABLE ${table} REPLICA IDENTITY FULL;`).join(' ')}` +
+        ' -- rows already written to the WAL keep the identity they were written with',
+    });
+  }
+}

package/src/server-render-client.ts

@@ -0,0 +1,96 @@
+// What a live client IS on the server: one that serves the first render and opens no socket.
+//
+// The rule it exists for is `@ultimat3/ui`'s, one package over — no runtime and no DOM is a SERVER
+// RENDER, and a server render gets an honest account of itself rather than a throw. A page whose
+// whole body reads a live query could not server-render at all before this: `useConnection()` threw
+// `X_LIVE_CLIENT_MISSING` and the route answered 500 (issue #271).
+//
+// It implements `LiveClientLike` and imports NO connection lifecycle — no `LiveClient`, no
+// heartbeat, no wire protocol. Measured: reaching the class from here costs every island that
+// calls `useLive` 18 kB it can never run.
+
+import type { LiveClientLike, LiveHandle, LiveQueryRef, SignalFactory } from './client-contract';
+import { ServerRenderLiveError } from './errors';
+import type { JsonValue, Row } from './json';
+import type { LiveState } from './live-rows';
+
+/**
+ * A signal that never changes, because nothing on the server can change it: one render, one pass,
+ * no reactive runtime. The setter is kept rather than dropped so a caller that writes through it
+ * reads its own write back — a signal that swallowed writes would be a different lie.
+ */
+const inertSignal: SignalFactory = <T>(initial: T): [() => T, (next: T) => void] => {
+  let held = initial;
+  return [
+    (): T => held,
+    (next: T): void => {
+      held = next;
+    },
+  ];
+};
+
+/** Frozen, so a handle a page holds cannot be turned into a result set by writing to it. */
+const NO_ROWS: readonly Row[] = Object.freeze([]);
+
+/** Nothing was subscribed, so nothing is released — and a teardown never fails a render. */
+const releaseNothing = (): void => undefined;
+
+/**
+ * The handle a server render gets for a live query: `loading`, never `offline` and never `live`.
+ *
+ * That is the one honest state — the rows arrive over a socket this render does not have, so the
+ * page's own loading fallback is what the document carries until hydration replaces it. `offline`
+ * would be read as a SETTLED answer (`state() !== 'loading'` is the gate `examples/dummy`'s feed
+ * uses), so an empty result set would render "you have no posts" for a feed that has some.
+ */
+function serverRenderHandle<R extends Row>(): LiveHandle<R> {
+  return {
+    rows: () => NO_ROWS as readonly R[],
+    state: (): LiveState => 'loading',
+    cursor: () => null,
+    unsubscribe: releaseNothing,
+    [Symbol.dispose]: releaseNothing,
+  };
+}
+
+/**
+ * Every member that can only mean "talk to the socket" refuses; every member a render READS
+ * answers what a server render actually is.
+ *
+ * `connected: true` is not a lie about the socket — `useConnection().offline` is a banner about
+ * THIS visitor's connectivity, and the request being served is the proof it is up. Answering
+ * `false` would server-render "you are offline" into every document, for a reader who is not, and
+ * then remove it on hydrate.
+ *
+ * It registers nothing, which is what makes ONE instance per process safe under concurrent
+ * renders: a client that kept a registration per `useLive` would grow by one entry per request,
+ * forever, and hold a row window with each.
+ */
+function build(): LiveClientLike {
+  return {
+    signal: inertSignal,
+    queue: undefined,
+    connected: true,
+    reconnectAt: () => null,
+    appUpdateAvailable: () => null,
+    useLive: <R extends Row>(_query: LiveQueryRef, _input: JsonValue): LiveHandle<R> =>
+      serverRenderHandle<R>(),
+    mutate: (): Promise<void> => {
+      throw new ServerRenderLiveError({ operation: 'mutate()' });
+    },
+    drain: (): Promise<void> => {
+      throw new ServerRenderLiveError({ operation: 'drain()' });
+    },
+    // A listener is accepted and never called: nothing on the server can change a queue that does
+    // not exist. Refusing here would break `setLiveClient`, which registers one unconditionally.
+    onQueueChange: () => releaseNothing,
+  };
+}
+
+let held: LiveClientLike | null = null;
+
+/** ONE per process, built on first use. It holds nothing per request — see `build` above. */
+export function serverRenderLiveClient(): LiveClientLike {
+  held ??= build();
+  return held;
+}

package/src/sync-node.ts

@@ -7,6 +7,7 @@
 import { type Clock, logger, markReady, reportError, systemClock, uuid } from '@ultimat3/core';
 import type { ChannelHub, Topic } from './channel';
 import { detach } from './detach';
+import { evictInChunks } from './drain-evictions';
 import { isClientFault } from './errors';
 import type { Transport, TransportSubscription } from './fanout';
 import type { LiveQueryRegistry } from './live-query';
@@ -187,8 +188,12 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
    * Everything one socket held, released once. Bun's `close` callback runs it, and so does a
    * revoked grant — a socket this node closes itself gets no callback in a unit test, and in
    * production the second run is the no-op every step here already is.
+   *
+   * Returns the presence leaves it started, which is the only step here that is not over when this
+   * function returns: `close` is a SYNCHRONOUS Bun callback and cannot await one, so the promise is
+   * both detached (that path has nobody to wait for it) and handed back (the drain does).
    */
-  const teardown = (socket: SyncSocket): void => {
+  const teardown = (socket: SyncSocket): readonly Promise<unknown>[] => {
     options.registry.unsubscribeSocket(socket.id);
     const topics = [...socket.topics] as Topic[];
     for (const name of topics) options.hub.unsubscribe(socket, name);
@@ -197,9 +202,17 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
     // A closed socket is a leave, said now rather than left to TTL: everyone else would otherwise
     // keep rendering a member who is provably gone for the rest of its window. The write is on the
     // bus and the close callback is synchronous, so it cannot be awaited here.
+    const leaves: Promise<unknown>[] = [];
     if (presence) {
-      for (const name of topics) detach(presence.leave(name, socket.id), 'presence.leave', name);
+      for (const name of topics) {
+        const leave = presence.leave(name, socket.id);
+        // Detached as well as returned: `detach` attaches the reporting catch, so a caller that
+        // awaits this later is awaiting a promise whose rejection is already handled.
+        detach(leave, 'presence.leave', name);
+        leaves.push(leave);
+      }
     }
+    return leaves;
   };
 
   /**
@@ -208,9 +221,9 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
    * because dropping the socket from the table is three of `teardown`'s five steps and the two it
    * misses are the ones another node can see.
    */
-  const evict = (socket: SyncSocket, code: number, reason: string): void => {
+  const evict = (socket: SyncSocket, code: number, reason: string): readonly Promise<unknown>[] => {
     socket.close(code, reason);
-    teardown(socket);
+    return teardown(socket);
   };
 
   /**
@@ -460,9 +473,12 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
       // five steps, and the two they skip are the ones the rest of the fleet can see. A drained
       // socket that never left its presence set is a member every other node renders for a full
       // TTL — during a rolling restart, beside the same client's reconnection under a new id —
-      // and its live subscriptions stay in the registry, so `entry.subscribers` never empties and
-      // the matcher, the shared window and the retained ring are pinned for the process's life.
-      for (const socket of [...sockets.all()]) evict(socket, CLOSE.goingAway, 'drain');
+      // and its live subscriptions stay in the registry, so `entry.subscribers` never empties.
+      //
+      // AWAITED, in chunks: a leave is a write to the shared set, so a drain that merely started
+      // them released, closed the hub and let the process exit with N·M writes still on the wire —
+      // which is that same full-TTL double vision, reached the long way round.
+      await evictInChunks([...sockets.all()], (socket) => evict(socket, CLOSE.goingAway, 'drain'));
       // Released once the sockets are gone rather than at the top: a client is entitled to its
       // patches for the whole grace window, and it is entitled to them *before* the hub the
       // fanout writes through is closed.

package/src/sync-upgrade.ts

@@ -101,12 +101,21 @@ export async function handleUpgrade(
       );
     }
   }
-  // Asked again, because `authenticate` is app code and awaiting it is awaiting a token service: a
-  // request that passed the check above can be parked there when SIGTERM lands, and the `accept`
-  // phase is over by the time it gets here. Upgrading then is the one socket that phase exists to
-  // refuse — the load balancer has already been told this node is out, so nothing takes it over. No
-  // second `tryAccept()`: that budget was spent above.
-  if (!deps.ready()) return shed(deps);
+  // BOTH facts asked again, because `authenticate` is app code and awaiting it is awaiting a token
+  // service: everything this request read above is history by the time it gets here.
+  //
+  // `ready`, because SIGTERM can land while the request is parked and the `accept` phase is over
+  // by now — upgrading then is the one socket that phase exists to refuse, on a node the load
+  // balancer has already been told is out.
+  //
+  // The socket COUNT, for the same reason and it was the half that was missing: a restart storm
+  // dials every client of a dead node at this one at once, each parked in the token service having
+  // passed the cap while the node still held nothing — so a node capped at 2 accepted as many
+  // sockets as there were parked requests, and `maxConnections` bounded nothing that a herd could
+  // reach. Sound because there is no await between this line and `server.upgrade`, and the count
+  // moves INSIDE it: Bun runs `websocket.open` synchronously there, which is where `sockets.add`
+  // runs. No second `tryAccept()`: that budget was spent above.
+  if (!deps.ready() || deps.socketCount() >= deps.maxConnections) return shed(deps);
   const data: WsData = {
     socketId: deps.newSocketId(),
     clientBuildId: url.searchParams.get('build') ?? deps.buildId,

package/src/type-pins.ts

@@ -7,7 +7,7 @@
 // stops catching the typo that makes a subscription match nothing.
 
 import type { Query } from '@ultimat3/query';
-import type { LiveHandle, Unsubscribe } from './client';
+import type { LiveClient, LiveClientLike, LiveHandle, Unsubscribe } from './client';
 import type { LiveRows } from './hooks';
 import type { LiveQueryHook, LiveQuerySource } from './query-hook';
 
@@ -70,3 +70,14 @@ export type _LiveRowsIsDisposable = Assert<[LiveRows] extends [Disposable] ? tru
 
 /** `channel.subscribe()`'s return must stay both callable and `Disposable`. */
 export type _UnsubscribeIsDisposable = Assert<[Unsubscribe] extends [Disposable] ? true : false>;
+
+/**
+ * The hook seam takes `LiveClientLike`, not `LiveClient` — a structural shape, so the server
+ * render's client can satisfy it without dragging the connection lifecycle into every island that
+ * calls `useLive` (measured: 8,368 B → 26,571 B). This is what keeps the two in step: a member
+ * `hooks.ts` needs and `LiveClient` stops providing fails HERE, at the build, rather than at the
+ * one app that registered a real client.
+ */
+export type _LiveClientSatisfiesTheHookSeam = Assert<
+  [LiveClient] extends [LiveClientLike] ? true : false
+>;