@ultimat3/realtime 19.3.1 → 19.3.3

package/CLAUDE.md

@@ -765,9 +765,13 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   `DEFAULT_HEARTBEAT_MS`, 15s; `0` disables) sends a `hello` — byte-identical to the opening one,
   since the frame has no resume list to leave out — plus one subscribe frame per topic, which is the
   node's presence heartbeat. It is **not** how a deploy is noticed: `socket.skewed` compares the
-  build id recorded at the upgrade against this node's, both fixed for the socket's life, so every
-  `hello` on one socket answers the same forever and `update-available` reaches a client on the
-  socket it opens against the *new* node. Two silent windows and the client closes with `4000` and
+  build the client claims (the `hello`'s `buildId`, which `sawHello` records on every one — the
+  latest is the record — or `?build=` on the dial) against this node's; a client says the same
+  build on every beat and the node's never moves while the socket is open, so every `hello` on one
+  socket answers the same forever and `update-available` reaches a client on the
+  socket it opens against the *new* node. The hello IS read — until 2026-09-07 only the dial was,
+  and a dial without `?build=` was recorded as this node's own id, so a client naming its build only
+  in the frame was current forever. Two silent windows and the client closes with `4000` and
   arms the reconnect. It is one
   self-re-arming tick on the injected `Scheduler`, not an interval: a client is either beating on a
   live socket or backing off toward a new one, never both. The 15s is the client's OWN number:

package/README.md

@@ -306,7 +306,7 @@ new LiveClient({ signal, connect, buildId, heartbeatMs: 15_000 }); // 0 disables
 | Default | `DEFAULT_HEARTBEAT_MS`, 15s. The client's own number and the only one: `realtime.heartbeatMs` in `app.config.ts` was deleted 2026-08-19 because nothing read it |
 | One beat | a `hello` — which carries no cursors at all; `HelloFrame` has no resume list, so a beat and an opening frame are byte-identical — plus one subscribe frame per topic held |
 | Why the topics | on the node, repeating the subscribe frame **is** the presence heartbeat; presence has no frame of its own in either direction |
-| Not a deploy check | `update-available` answers a skew between the build id recorded at the upgrade and the node's own, and neither can change on an open socket — so every `hello` on one socket answers the same forever. A client hears about a deploy on the socket it opens against the **new** node |
+| Not a deploy check | `update-available` answers a skew between the build the client claims — the `hello`'s `buildId`, or `?build=` on the dial; every hello is read and the latest one is the record — and the node's own. A client says the same build on every beat and the node's never moves while the socket is open, so every `hello` on one socket answers the same forever. A client hears about a deploy on the socket it opens against the **new** node |
 | Silence | nothing received for **two** intervals ⇒ close `4000` (a private-use code, so it is distinguishable in a log) and arm the reconnect. Judged from the last frame of any kind, since the point is that bytes still cross |
 | Not an interval | one armed tick, re-armed by itself, on the same injected `Scheduler` the reconnect uses — a client is either beating on a live socket or backing off toward a new one, never both |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "19.3.1",
+  "version": "19.3.3",
   "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": "19.3.1",
-    "@ultimat3/query": "19.3.1",
+    "@ultimat3/core": "19.3.3",
+    "@ultimat3/query": "19.3.3",
     "nats": "2.29.3"
   }
 }

package/src/client-frames.ts

@@ -3,6 +3,7 @@
 // every piece of the client a frame may touch, so the blast radius of a new frame kind is a
 // reviewable list rather than "whatever the router could reach through `this`".
 
+import { CLOSE } from './close-codes';
 import { advance } from './cursor';
 import type { JsonObject, JsonValue } from './json';
 import type { Registration, RowWindows } from './live-rows';
@@ -14,6 +15,17 @@ import type { Frame, PresenceMember } from './sync-protocol';
 /** Declared with the window it projects; re-exported here because the router is what writes it. */
 export type { LiveState, Registration } from './live-rows';
 
+/**
+ * The code a `reconnect` frame closes with: `CLOSE.drain`, the same number the node uses for a
+ * drain it closes itself, so a log reads one code for one event whichever side closed first. It
+ * was 1001, and a browser refuses that from script: `WebSocket.close()` throws
+ * `InvalidAccessError: The close code must be either 1000, or between 3000 and 4999` — measured
+ * in Chrome, an uncaught exception in every tab on every node drain. The reconnect still happened,
+ * because the node closed the socket a moment later; the exception was the only trace.
+ * `HEARTBEAT_TIMEOUT_CODE` in `client.ts` is the sibling, for the other close the client makes.
+ */
+export const RECONNECT_CODE = CLOSE.drain;
+
 /**
  * Everything an inbound frame is allowed to reach. Narrow on purpose — a router that took the
  * client itself could touch the reconnect timer, the socket and the outbound path, none of which
@@ -151,7 +163,7 @@ export function applyFrame<T extends TableMap>(frame: Frame, target: ClientFrame
       // Order is load-bearing: arming first is what makes the close this triggers keep the delay
       // the node assigned to *this* socket instead of falling back to a local backoff.
       target.scheduleReconnect(frame.afterMs);
-      target.closeSocket(1001, frame.reason);
+      target.closeSocket(RECONNECT_CODE, frame.reason);
       return;
     }
     case 'update-available': {

package/src/client.ts

@@ -45,7 +45,11 @@ export type {
 /** The four states a live subscription renders. Declared with the window that holds them. */
 export type { LiveState } from './live-rows';
 
-/** Private-use close code (4000–4999), so a heartbeat timeout is distinguishable in a log. */
+/**
+ * Private-use close code (4000–4999), so a heartbeat timeout is distinguishable in a log. A browser
+ * accepts only 1000 and 3000–4999 from script; `RECONNECT_CODE` (`client-frames.ts`) is the
+ * sibling, for the close a `reconnect` frame makes.
+ */
 const HEARTBEAT_TIMEOUT_CODE = 4000;
 
 /** The default reporter: `console.error`, never core's `logger` — that writes `process.stderr`. */
@@ -395,10 +399,11 @@ export class LiveClient<T extends TableMap = TableMap> {
    * heartbeat: subscribing IS being in the room, so a client that stopped repeating it is swept
    * out of every room it is still receiving from.
    *
-   * It is NOT how a deploy is noticed. `socket.skewed` compares the build id the upgrade recorded
-   * against this node's, both fixed for the socket's whole life, so every `hello` on one socket
-   * gets the same answer forever; `update-available` reaches a client on the socket it opens
-   * against the *new* node, which is a reconnect and never a beat.
+   * It is NOT how a deploy is noticed. `socket.skewed` compares the build id this client says —
+   * the `hello`'s own `buildId`, the same on every beat, or `?build=` on the dial — against the
+   * node's, and neither moves while the socket is open, so every `hello` on one socket gets the
+   * same answer forever; `update-available` reaches a client on the socket it opens against the
+   * *new* node, which is a reconnect and never a beat.
    */
   #beat(): void {
     this.#send(this.#hello());

package/src/close-codes.ts

@@ -0,0 +1,21 @@
+// The close codes this protocol speaks, defined once below both halves. `socket.ts` (the node's
+// registry) and `client-frames.ts` (browser code) each need one of these and neither may import
+// the other — the client must not pull the node's registry into the tab — so the table lives here,
+// a leaf with no import at all, and `socket.ts` re-exports it for the node-side files that already
+// read `CLOSE` from there.
+//
+// 1000–1015 are the RFC 6455 codes; 4000–4999 are private use. A browser accepts only 1000 and
+// 3000–4999 from script (`WebSocket.close()` throws `InvalidAccessError` on anything else), which
+// is why every code the CLIENT sends is in the private range and why `goingAway` (1001) is a code
+// only the node may close with.
+
+export const CLOSE = {
+  normal: 1000,
+  goingAway: 1001,
+  policy: 1008,
+  overloaded: 1013,
+  versionSkew: 4000,
+  idle: 4001,
+  /** The node drains, or the client obeys a `reconnect` frame: one event, one code, either side. */
+  drain: 4002,
+} as const;

package/src/socket.ts

@@ -16,18 +16,12 @@ import {
   systemClock,
   uuid,
 } from '@ultimat3/core';
+import { CLOSE } from './close-codes';
 import { encode, type Frame } from './sync-protocol';
 import { AcceptBudget } from './thundering-herd';
 
-export const CLOSE = {
-  normal: 1000,
-  goingAway: 1001,
-  policy: 1008,
-  overloaded: 1013,
-  versionSkew: 4000,
-  idle: 4001,
-  drain: 4002,
-} as const;
+/** Defined in `close-codes.ts`, below both halves; re-exported for the node-side files. */
+export { CLOSE } from './close-codes';
 
 /**
  * The slice of Bun's `ServerWebSocket` this package uses. Structural, so tests need no server.
@@ -49,7 +43,11 @@ export interface WsLike {
 
 export interface SyncSocketOptions {
   readonly ws: WsLike;
-  /** Build id the *client* reported in `hello`. Version skew is a first-class connection state. */
+  /**
+   * Build id the *client* reported on the dial (`?build=`), or this node's own when it sent none;
+   * `sawHello` overwrites it with what the `hello` frame says. Version skew is a first-class
+   * connection state.
+   */
   readonly clientBuildId: string;
   readonly serverBuildId: string;
   readonly actor?: Actor | null;
@@ -113,7 +111,6 @@ export function actorIdOf(actor: Actor | null): string | null {
  */
 export class SyncSocket {
   readonly id: string;
-  readonly clientBuildId: string;
   readonly serverBuildId: string;
   readonly openedAt: number;
   /** Channel topics (tier 1). Live-query subscriptions are keyed separately, by sid. */
@@ -149,13 +146,14 @@ export class SyncSocket {
   readonly #clock: Clock;
   readonly #maxBufferedBytes: number;
   readonly #maxDroppedFrames: number;
+  #clientBuildId: string;
   #closed = false;
 
   constructor(options: SyncSocketOptions) {
     this.#ws = options.ws;
     this.#clock = options.clock ?? systemClock;
     this.id = options.id ?? uuid();
-    this.clientBuildId = options.clientBuildId;
+    this.#clientBuildId = options.clientBuildId;
     this.serverBuildId = options.serverBuildId;
     this.actor = options.actor ?? null;
     this.#maxBufferedBytes = options.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
@@ -185,9 +183,26 @@ export class SyncSocket {
     return this.#closed;
   }
 
+  /** The build the client last claimed: the dial's `?build=`, then whatever its `hello` said. */
+  get clientBuildId(): string {
+    return this.#clientBuildId;
+  }
+
+  /**
+   * The `hello` frame is the documented place a client names its build, and until 2026-09-07 the
+   * node never read it: `clientBuildId` came from the dial's `?build=` alone and defaulted to this
+   * node's OWN id when the query was absent — so a client that said `hello` from any build at all
+   * was deemed current forever, and `update-available` never came. Measured on ai-maxxing: a page
+   * sending `buildId: "dev"` in every hello to a node on `46db23f57d6ef969`. The last word wins,
+   * and the hello is the later one; `?build=` still works for a dial that carries it.
+   */
+  sawHello(buildId: string): void {
+    this.#clientBuildId = buildId;
+  }
+
   /** A skewed client gets an `update-available` frame; it is never silently served a new shape. */
   get skewed(): boolean {
-    return this.clientBuildId !== this.serverBuildId;
+    return this.#clientBuildId !== this.serverBuildId;
   }
 
   /** `false` means the frame was dropped by backpressure — the caller must mark state stale. */

package/src/sync-frames.ts

@@ -76,6 +76,9 @@ export function createFrameRouter(options: FrameRouterOptions): FrameRouter {
   async function apply(socket: SyncSocket, frame: Frame): Promise<void> {
     switch (frame.type) {
       case 'hello': {
+        // Before `skewed` is asked: the frame is the client's word on its build, and the upgrade
+        // may have recorded none (a dial without `?build=` defaults to this node's own id).
+        socket.sawHello(frame.buildId);
         socket.send({
           type: 'hello',
           v: PROTOCOL_VERSION,

package/src/sync-upgrade.ts

@@ -14,6 +14,12 @@ import type { AcceptBudget, Rng } from './thundering-herd';
  */
 export interface WsData {
   readonly socketId: string;
+  /**
+   * `?build=` off the dial, or this node's own id when the dial carried none. A starting value,
+   * not the verdict: the `hello` frame's `buildId` overwrites it (`SyncSocket.sawHello`), so a
+   * client that names its build only in the frame — the documented place — is not deemed current
+   * forever for having sent no query.
+   */
   readonly clientBuildId: string;
 }
 
@@ -118,6 +124,7 @@ export async function handleUpgrade(
   if (!deps.ready() || deps.socketCount() >= deps.maxConnections) return shed(deps);
   const data: WsData = {
     socketId: deps.newSocketId(),
+    // The node's own id is "not skewed until the hello says so", never "current forever".
     clientBuildId: url.searchParams.get('build') ?? deps.buildId,
   };
   // Before the upgrade, never after: `server.upgrade` runs `websocket.open` synchronously and does