@ultimat3/realtime 9.0.0 → 11.0.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:
@@ -35,6 +43,15 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   **The array alone would have fixed the build** and is not why the split exists: tree-shaking is
   a bundler's discretion, `export * from` or a namespace import defeats it, and "the client entry
   cannot reach the bus" is a contract rather than an optimisation.
+- **Two entries means a specifier naming a third does not resolve, and a `fix:` is pasted.**
+  `local-store.ts`'s `X_NOT_IMPLEMENTED` told the caller to import `createOpfsLocalStore` from
+  `@ultimat3/realtime/browser` — a subpath `exports` has never declared — so the one instruction
+  the refusal carried ended in a module-resolution failure, in the package whose own rules cite
+  axiom 4. Its alternative, `persist: false` on the query, was the same defect twice: `query()`
+  does not accept `persist` either. `fix-specifier.test.ts` is the build error — every
+  `@ultimat3/realtime/<subpath>` written in shipped source must be a key of `exports`, comments
+  included, because a comment naming a subpath that does not exist is the next fix line's source.
+  It cannot see WHICH names a fix promises, so the OPFS one is pinned by name beside it.
 - **`@ultimat3/realtime/server` needs its own `paths` entry in `tsconfig.base.json`**, beside
   `@ultimat3/admin/dev`'s. `@ultimat3/*` maps `realtime/server` to `packages/realtime/server/src`,
   which does not exist, and the root program has no `node_modules/@ultimat3` symlink to fall back
@@ -196,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
@@ -259,6 +287,21 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   whose non-key columns happen to be NULL sends the bytes a FULL one does, so counting absent keys
   would undercount exactly the rows a policy is most likely to misjudge. A hard refusal in the
   `x verify` step is the follow-up and lives in `@ultimat3/cli`.
+- **The replication session pins its own output formats, `As of 2026-08-23`.** Postgres sends every
+  WAL value as TEXT and `pg-values.ts` reads a `timestamptz` by matching postgres' ISO spelling,
+  keeping the raw text when it does not match — deliberately, because a wrong instant is worse than
+  a string. That makes the SERVER's `DateStyle` load-bearing: `SQL`, `German` or `Postgres` sends
+  every timestamp down the fallback, the shared window holds `Date`s while the patch holds text,
+  `compareValues` falls to string comparison, and one edit to one column jumps its row to the top
+  of every `orderBy('createdAt','desc')` feed for every subscriber — the exact defect the decode
+  exists to close, re-opened by a GUC. `pg-connection.ts` therefore sends
+  `options: '-c datestyle=ISO -c intervalstyle=postgres -c extra_float_digits=3'` in the startup
+  packet, byte for byte what postgres' own logical-replication client sends
+  (`libpqwalreceiver.c`) — which is why a walsender accepts it. On **every** session this class
+  opens, not only the replicating one: one session shape is one thing to reason about, and the
+  advisory-lock connection is the same class. A server that refuses one answers `ErrorResponse` at
+  startup, so the replicator fails to boot with the server's own words rather than mis-sorting a
+  feed behind a warning nobody reads. `pg-connection.test.ts` pins the packet.
 - A change lsn is `<16 hex commit position><8 hex row position in that transaction>`. Never order by
   either half alone: the commit lsn repeats within a transaction, and per-record WAL positions are
   not monotonic across transactions. Never make it depend on wall time, the entity list or a process
@@ -301,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.
@@ -523,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
@@ -690,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 |
@@ -716,10 +800,15 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 ## Commands
 
 ```
-bun test                                  # from packages/realtime
+bun test packages/realtime/src            # from the REPO ROOT, never from packages/realtime
 bun run typecheck
 ```
 
+**The root is not a preference.** `bunfig.toml`'s preload installs `@ultimat3/testing`'s matchers
+and Bun reads `bunfig.toml` from the cwd, so `bun test` inside this directory loads none and six
+tests fail on a missing matcher — this package's suite reading red for the shell it was run in.
+CI's `package` job spawns `bun test packages/<pkg>` with `cwd` at the root for the same reason.
+
 Changing a frame shape means adding a fixture to `sync-protocol.test.ts` — the round-trip test
 fails if a kind has no fixture — and bumping `PROTOCOL_VERSION` **when the change makes an old
 frame unreadable in either direction**. An *additive optional* field (`snapshot.entity`, 2026-08)

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.
@@ -256,7 +269,7 @@ that outlasts the deploy. The design confronts it with exactly two paths and no
 | **snapshot** | out of window, past `maxLagMs`, or past `reconnectBudget` | one bounded indexed query |
 
 A `LiveCursor` is `lsn` + result-set `digest` + last-seen `ids` + `count`. The digest is
-order-sensitive, so a re-sort is detected; the ids let a delta be re-filtered per subscriber, because
+order-sensitive and server-side (see `cursor.ts#digestOf` for why a client cannot reproduce one); the ids let a delta be re-filtered per subscriber, because
 the retained window stores **pre-policy** patches. `resumeFrom()` picks the path,
 `shouldResnapshot()` explains it, and the budget is a cost model in patch-equivalents
 (`snapshotCost: 250` = "replaying 250 patches costs a snapshot") so the expensive path is *chosen*,
@@ -348,7 +361,9 @@ wire twice by a reconnect that raced an ack.
   would put the write the server refused back on the screen. Idempotent for a key the log does not
   hold, because a denial can arrive twice and tier 2 records nothing to undo.
 - **A delta resume leaves the digest unverified** (`DIGEST_UNVERIFIED`). Only a snapshot re-establishes
-  it. `verifyDigest()` is how a client detects drift and asks for a fresh one.
+  it. The digest is the SERVER's own — nothing on the client reproduces it, and `verifyDigest()`,
+  which claimed otherwise and had no caller, is deleted (2026-08-23). What detects drift on the
+  client is the server's `desynced` mark and the re-snapshot it triggers.
 - **Backpressure drops patch frames.** That is safe *only* because a re-snapshot is cheap: the drop
   is recorded on the socket (`desynced`) and the next delivery re-snapshots rather than diverging.
 - **A dropped CHANNEL frame is not safe, and is not repaired.** A topic has no cursor, no mark and
@@ -410,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
@@ -504,10 +524,13 @@ wire twice by a reconnect that raced an ack.
   running half: one per change delivered off a relation that is not FULL, so the decisions it
   actually cost are countable rather than silent. A hard refusal at `x verify` time is the
   follow-up.
-- Tier 3's OPFS SQLite store is browser-only and throws until the browser entry ships; `MemoryLocalStore`
-  implements the full journal/rollback/replay semantics today. It holds membership and the journal;
-  the row values are the client's one `IdentityMap`, which is what a browser store has to inherit
-  rather than re-implement.
+- Tier 3's OPFS SQLite store is browser-only, is **not built**, and throws `X_NOT_IMPLEMENTED` on
+  call. `createOpfsLocalStore` is exported from `.` and stays there when it ships — there is no
+  third entry to wait for, and the refusal used to name one (`@ultimat3/realtime/browser`, a
+  subpath `exports` never declared). `MemoryLocalStore`, beside it on `.`, implements the full
+  journal/rollback/replay semantics today and is what the refusal's `fix:` names. It holds
+  membership and the journal; the row values are the client's one `IdentityMap`, which is what a
+  browser store has to inherit rather than re-implement.
 - The identity map is **per client**, in memory, and it is not a query cache: it answers "what is
   row X now", never "have I run this query before". Nothing evicts by time or size — a row lives
   exactly as long as a window or a table holds it.
@@ -518,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": "9.0.0",
+  "version": "11.0.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": "9.0.0",
-    "@ultimat3/query": "9.0.0",
+    "@ultimat3/core": "11.0.0",
+    "@ultimat3/query": "11.0.0",
     "nats": "2.29.3"
   }
 }

package/src/change-buffer.ts

@@ -51,6 +51,12 @@ function patchBytes(patch: RowPatch): number {
 
 export class RingChangeBuffer implements ResumeSource {
   readonly #rings = new Map<string, Ring>();
+  /**
+   * Query hashes whose ring was dropped, so the ring the NEXT change builds knows it does not
+   * carry the history before it. A `Set` of ids and not a `Map` of lsns: what the next ring is
+   * complete from is its own first patch, which only that patch can name.
+   */
+  readonly #forgotten = new Set<string>();
   readonly #capacity: number;
   readonly #maxQueries: number;
   readonly #maxBytesPerQuery: number;
@@ -71,7 +77,17 @@ export class RingChangeBuffer implements ResumeSource {
 
   append(qid: string, patch: RowPatch): void {
     const existing = this.#rings.get(qid);
-    const ring: Ring = existing ?? { patches: [], bytes: 0, evictedThrough: null };
+    // A ring RE-CREATED after a `forget` is complete only from this patch onward: everything before
+    // it went with the ring, and — on the `unsubscribe` path — the entry went too, so the changes
+    // in between were never appended at all. `evictedThrough` at its own first lsn is what makes
+    // `since` refuse a cursor from before that, which it could not do while the field came back
+    // `null` and every earlier cursor read as in-window on a ring that had held none of it.
+    const reborn = this.#forgotten.delete(qid);
+    const ring: Ring = existing ?? {
+      patches: [],
+      bytes: 0,
+      evictedThrough: reborn ? patch.lsn : null,
+    };
     ring.patches.push(patch);
     const cost = patchBytes(patch);
     ring.bytes += cost;
@@ -124,9 +140,29 @@ export class RingChangeBuffer implements ResumeSource {
    */
   forget(qid: string): void {
     const ring = this.#rings.get(qid);
-    if (!ring) return;
-    this.#bytes -= ring.bytes;
-    this.#rings.delete(qid);
+    if (ring !== undefined) {
+      this.#bytes -= ring.bytes;
+      this.#rings.delete(qid);
+    }
+    // The qid is remembered, the patches are not — and unconditionally, because the ring being
+    // absent is not the history being intact. Both callers lose history here and neither could say
+    // so: `LiveQueryRegistry.unsubscribe` drops the ENTRY, so every change until the next
+    // subscriber is never appended at all, and the LRU fires on a query that still has LIVE
+    // subscribers. Either way the next `append` was building a ring that reported itself complete
+    // from the beginning of time, so a client reconnecting inside `maxLagMs` folded a partial patch
+    // list onto a stale window with `shouldResnapshot` answering `in-window` and nothing marked
+    // desynced — permanently divergent on a healthy socket. What the tombstone costs in exchange is
+    // a resume that could have been a delta taking the snapshot path; that is one bounded read, and
+    // it is the direction this package errs in everywhere else.
+    this.#forgotten.add(qid);
+    // Bounded like everything else here: insertion-ordered, so the oldest tombstone goes first.
+    // Losing one costs a resume that could have been a delta; keeping them unbounded costs memory
+    // a client-chosen input mints at will.
+    while (this.#forgotten.size > this.#maxQueries) {
+      const oldest = this.#forgotten.values().next();
+      if (oldest.done === true) break;
+      this.#forgotten.delete(oldest.value);
+    }
   }
 
   get queryCount(): number {

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/cursor.ts

@@ -105,17 +105,23 @@ export function makeCursor(
   };
 }
 
-/** FNV-1a over `id:row` pairs in result order — order-sensitive, so a re-sort is detected. */
+/**
+ * FNV-1a over `id:row` pairs in result order — order-sensitive, so a re-sort is detected.
+ *
+ * **Server-side only, and it is not reproducible by a client.** `verifyDigest()` used to sit here
+ * and was DELETED (2026-08-23): it was documented as "how a client detects drift", had no caller
+ * outside its own test, and could not have had one. Three reasons, any one of them fatal.
+ * `canonicalJson` tags a `Date` as `Date(<epoch>)` while the client holds the ISO string
+ * `JSON.stringify` sent it. A delta-resumed cursor carries `DIGEST_UNVERIFIED`, so the check
+ * answered `false` for every cursor a delta produced — which is the only state drift can be
+ * detected in. And `identity-map.ts` MERGES columns across queries on purpose, so a client's row
+ * for one id is legitimately a superset of the row any single snapshot sent: an app with two reads
+ * over one entity would have reported permanent drift.
+ */
 export function digestOf(rows: readonly Row[]): string {
   return fnv1a(rows.map((row) => `${row.id}:${canonicalJson(row)}`).join(';'));
 }
 
-/** Client-side drift check: a mismatch after delta resumes is a request for a fresh snapshot. */
-export function verifyDigest(cursor: LiveCursor, rows: readonly Row[]): boolean {
-  if (cursor.digest === DIGEST_UNVERIFIED) return false;
-  return cursor.digest === digestOf(rows);
-}
-
 export function shouldResnapshot(
   cursor: LiveCursor,
   available: readonly RowPatch[] | null,

package/src/detach.ts

@@ -0,0 +1,27 @@
+// Work nobody is waiting on: a presence leave from a synchronous close, a sweep on a timer, a
+// fanout off the change bus. Split out of `sync-node.ts` at the 500-line ceiling, and it is the
+// natural seam — the function closes over nothing the node holds.
+
+import { logger, renderThrowable, reportError } from '@ultimat3/core';
+
+/**
+ * It reaches the bus or a policy, so it can fail; failing must not take a socket or the process
+ * with it, and must not be silent either, or "the room still shows someone who left" and "that
+ * change reached nobody" have nothing to read. `operation` stays low cardinality so the monitor
+ * can group on it; the topic or entity goes in `at`.
+ *
+ * `renderThrowable` and never `String(error)`: this is the one frame whose whole job is not to
+ * throw, and `String()` on a null-prototype throwable raises inside it — the detach's own `catch`,
+ * with nothing above it to answer. `channel.ts` already imports it for the same reason.
+ */
+export function detach(work: Promise<unknown>, operation: string, at?: string): void {
+  void work.catch((error: unknown) => {
+    logger.error(`${operation} failed`, {
+      ...(at === undefined ? {} : { at }),
+      error: renderThrowable(error),
+    });
+    // Nobody is awaiting this, so the log is the only trace it leaves — and a log is not a signal
+    // anyone is paged on. The bus is this node's dependency, never the client's.
+    reportError(error, { source: 'realtime', scope: { operation } });
+  });
+}

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);
+  }
+}