@ultimat3/realtime 27.14.0 → 27.14.1

package/CLAUDE.md

@@ -103,10 +103,10 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   `staleChanges`). **A gap is detected**: the replicator stamps `producer` + `seq`; a skipped
   sequence — or a NEW producer after a known one — stales every window; `refillWindowInLane` replaces it.
 - **A bulk write stales only its entity's readers**: windows + channel topics, `invalidate(entity)`
-  on both from `onBulk`. **A stale window's re-read re-snapshots EVERY subscriber**, before the lsn
+  on both from `onBulk` (channels: not a `recordPublisher` table). **A stale window's re-read re-snapshots EVERY subscriber**, before the lsn
   guard, even on a non-match (`live-replicator-bulk`, `live-fanout` tests).
 - **A WINDOW is per TENANT**: its id is `windowId(queryHash(name, input), tenant)` (`live-tenant.ts`;
-  tenant = the subscriber's `actor.orgId`). This package owns no hash. The read runs `readFor`
+  tenant = the subscriber's `actor.orgId`). The read runs `readFor`
   (`live-definition.ts`): the node's ctx, a service actor carrying ONLY that org — never the
   subscriber. A cursor naming another window is a cold start; `reauthorize` re-seats a
   subscription whose actor changed org (`live-tenancy.test.ts`; `docs/history/realtime.md`).
@@ -278,7 +278,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   (with its cursor) and per topic.
 - **The client beats** (`DEFAULT_HEARTBEAT_MS` 10 s = default ttl / 3, pinned by
   `client-heartbeat.test.ts`; `0` disables): a `hello` plus one subscribe per topic. Two silent
-  windows close with `4000`. **The node names the beat: `hello.heartbeatMs`** — `Heartbeat.follow`
+  windows after an UNANSWERED beat close with `4000`. **The node names the beat: `hello.heartbeatMs`** — `Heartbeat.follow`
   per socket; the engine reaps ports on the longer of its own and the node's.
 - **There is ONE `backoffDelay`, `@ultimat3/core`'s, counted from 1** — `policyDelay()` maps a
   `BackoffPolicy` onto it; `bun run flight-copies` refuses a second curve.
@@ -312,7 +312,7 @@ bun test packages/realtime/src   # from the REPO ROOT
 bun run typecheck
 ```
 
-`bunfig.toml`'s preload installs `@ultimat3/testing`'s matchers; Bun reads it from the cwd.
+`bunfig.toml`'s preload (matchers) is read from the cwd.
 
 Changing a frame shape means a fixture in `sync-protocol.test.ts` (the round-trip test fails
 without one) and bumping `PROTOCOL_VERSION` **when an old frame becomes unreadable in either

package/package.json

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

package/src/client-heartbeat.ts

@@ -39,6 +39,8 @@ export class Heartbeat {
   readonly #options: HeartbeatOptions;
   #cancel: (() => void) | null = null;
   #lastSeen = 0;
+  /** Whether a frame arrived since this socket last asked (the opening `hello`, then each beat). */
+  #answered = false;
   /** The beat in force on THIS socket: the option's, until the node's `hello` names another. */
   #intervalMs: number;
 
@@ -58,6 +60,7 @@ export class Heartbeat {
     this.#intervalMs = this.#options.intervalMs;
     if (this.#intervalMs <= 0) return;
     this.#lastSeen = now;
+    this.#answered = false;
     this.#arm();
   }
 
@@ -78,6 +81,7 @@ export class Heartbeat {
   /** A frame arrived. Anything counts: the point is that bytes still cross in this direction. */
   saw(now: number): void {
     this.#lastSeen = now;
+    this.#answered = true;
   }
 
   stop(): void {
@@ -98,10 +102,14 @@ export class Heartbeat {
     // Two windows, not one: a beat and the answer to it share the window they were sent in, so a
     // single quiet interval is a slow round trip and not a dead socket. Nothing is re-armed after
     // a silence — `onSilence` drops the socket, and the next `start()` is the next connection's.
-    if (now - this.#lastSeen > this.#intervalMs * 2) {
+    // And only when the last beat went UNANSWERED: a hidden tab's timers are throttled (Chrome runs
+    // a chained timer about once a minute), so a late tick on a socket that answered every beat it
+    // was sent is the page's clock, not the socket — dropping it churned every background tab.
+    if (!this.#answered && now - this.#lastSeen > this.#intervalMs * 2) {
       this.#options.onSilence();
       return;
     }
+    this.#answered = false;
     this.#options.beat();
     this.#arm();
   }

package/src/json.ts

@@ -74,9 +74,24 @@ export function changedColumns(before: JsonObject | null, after: JsonObject): Js
   return out;
 }
 
-function sameJson(a: JsonValue | undefined, b: JsonValue | undefined): boolean {
-  if (a === b) return true;
-  if (a === undefined || b === undefined || a === null || b === null) return false;
-  if (typeof a !== 'object' || typeof b !== 'object') return false;
-  return JSON.stringify(a) === JSON.stringify(b);
+/**
+ * Structural equality over the value domain: arrays by position, plain objects by key whatever
+ * their order (Postgres `jsonb` reorders keys), a `Date` by its time. A JSON column is a fresh
+ * object on every read, so identity said "changed" for every re-read of an unchanged row.
+ */
+export function sameJson(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
+  if (a instanceof Date || b instanceof Date) {
+    return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+  }
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((item, index) => sameJson(item, b[index]));
+  }
+  const left = a as Record<string, unknown>;
+  const right = b as Record<string, unknown>;
+  const keys = Object.keys(left);
+  if (keys.length !== Object.keys(right).length) return false;
+  return keys.every((key) => Object.hasOwn(right, key) && sameJson(left[key], right[key]));
 }

package/src/live-replicator.ts

@@ -151,8 +151,11 @@ export async function startLiveReplicator(options: LiveReplicatorOptions): Promi
       if (stopped) return;
       const table = tableOf(change.entity);
       registry.invalidate(table);
-      // Channels too, or a tab seated on one held the pre-update rows with nothing to re-read.
-      options.channels?.invalidate(table);
+      // Channels too, or a tab seated on one held the pre-update rows with nothing to re-read —
+      // unless a `recordPublisher` claims the table, as `onChange` asks: the app's own publish is
+      // its channel delivery, bulk writes included, and a replay-gap on every `updateWhere` sent
+      // every seated tab back to a full catch-up read for rows it was already being sent.
+      if (!isPublishedTable(table)) options.channels?.invalidate(table);
     },
   };
 

package/src/record-synced.ts

@@ -3,6 +3,7 @@
 // state — it answers what moved, and the store decides who hears about it.
 
 import type { Row } from '@ultimat3/core/page';
+import { sameJson } from './json';
 import type { RecordKey } from './record-key';
 
 export class SyncedLayer {
@@ -44,7 +45,9 @@ export class SyncedLayer {
   /**
    * One server write. Merged, never replaced: a projection that selected fewer columns must not
    * blank the columns another is rendering, so an omitted (or `undefined`) field is left alone.
-   * Answers the row as it now stands, and whether anything in it changed.
+   * Answers the row as it now stands, and whether anything in it changed. Compared STRUCTURALLY:
+   * a JSON column is a fresh array or object on every read, and by identity every catch-up, poll
+   * and reconnect moved every row. An unmoved column keeps its object, so its readers stay put.
    */
   merge(rk: RecordKey, columns: Row): { readonly row: Row; readonly changed: boolean } {
     // A restored row is a guess from disk: the server's first answer is the whole truth.
@@ -53,7 +56,8 @@ export class SyncedLayer {
     let changed = current === undefined;
     for (const [column, value] of Object.entries(columns)) {
       if (value === undefined) continue;
-      if (current === undefined || current[column] !== value) changed = true;
+      if (current !== undefined && sameJson(current[column], value)) continue;
+      changed = true;
       next[column] = value;
     }
     if (!changed && current !== undefined) return { row: current, changed: false };

package/src/record-tx.ts

@@ -3,6 +3,7 @@
 // over the OLD row must become `+ 1` over the row the server just sent, never the stale sum.
 
 import type { ConflictPolicy, Row } from '@ultimat3/core/page';
+import { sameJson } from './json';
 
 /** One table as a mutator's `local` half sees it, keyed by record type (the entity's name). */
 export interface LocalTable<R extends Row = Row> {
@@ -45,13 +46,16 @@ export interface ReplayResult {
   readonly failed: readonly string[];
 }
 
-/** Shallow content equality — a replay producing the same columns must not re-render anything. */
+/**
+ * Content equality, column by column and STRUCTURAL within one (`sameJson`) — a replay producing
+ * the same columns must not re-render anything, and a twin's array is a fresh one every replay.
+ */
 export function sameRow(a: Row | null, b: Row | null): boolean {
   if (a === b) return true;
   if (a === null || b === null) return false;
   const keys = Object.keys(a);
   if (keys.length !== Object.keys(b).length) return false;
-  return keys.every((key) => Object.hasOwn(b, key) && a[key] === b[key]);
+  return keys.every((key) => Object.hasOwn(b, key) && sameJson(a[key], b[key]));
 }
 
 export function replayOverlays(