@ultimat3/realtime 29.1.0 → 29.3.0

package/CLAUDE.md

@@ -164,8 +164,6 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   `upgrade()`, as Bun does.
 - **A grant expires; a socket does not**: expired grants are re-decided on an interval
   (`hub.onActorChange`, `registry.reauthorize`). No `refresh` = close `1008`; one that raises retries.
-- **Every `socket.send` reads its answer**: a dropped subscribe reply marks it desynced; a dropped
-  roster logs `sync.presence_roster_dropped`; `drain()` returns `DrainedSocket[]` (`notified`).
 - **Inbound frames run in a lane, never the socket**: `subscribe` is `sub:<sid>` or `topic:<name>`,
   everything else unlaned (`frame-lanes.ts`); a lane exists only while work is queued.
 - **A dropped `records` frame is counted AND repaired**: per-node `seq`/`epoch` per channel; a refused
@@ -256,6 +254,8 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   `useQuery`'s input is read once, at call time.
 - **`useRecords(type, selection)` holds the TYPE** (`retainType`): `ready` at once, recomputed per
   change to that type, no row of it evicted while held; the last type hold evicts what it spared.
+- **Read hooks answer the SAME object until what they show moved** (`keptAnswer`); a `where`
+  reader hears only keys it shows or keeps (history, 2026-10-29).
 - Every subscription handle is `Disposable`; `[Symbol.dispose]` IS the release. Type claims go in
   `type-pins.ts`.
 - **The outbox**: only `pending` is sendable; `drain()` is one chained pass at a time; `#epoch` is
@@ -282,9 +282,6 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   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.
-
-## Rules for code here
-
 - Never a bare `Error`. Never `any`. Never `Date.now()` — take a `Clock` (`monotonic()` for durations).
 
 ## The page boot
@@ -312,7 +309,6 @@ bun test packages/realtime/src   # from the REPO ROOT
 bun run typecheck
 ```
 
-`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/README.md

@@ -251,6 +251,7 @@ const pair = useRecords('posts', [postId]);                         // those key
 const runs = useRecords<Run>('runs', {                              // EVERY `runs` record on the page
   where: (run) => run.state !== 'done',
   order: (a, b) => (a.startedAt < b.startedAt ? 1 : -1),
+  throttleMs: 1_000,                                                // optional: at most once a second
 });
 const like = useMutation(LIKE_POST);                                // await like(input); like.pending
 const connection = useConnection();                                 // .offline .online .reconnectAt .updateAvailable
@@ -279,6 +280,8 @@ same type `@ultimat3/ui` renders.
 | A query ref is `{ name, live?, entity? }`, never the query VALUE | importing a `query()` drags its read path into the island (698,801 B measured) |
 | Lists hold keys; rows are the store's | a record updated by any answer or frame re-renders every list showing it, with no refetch |
 | A list that must GROW with the store is `useRecords(type, { where?, order? })` | a `useQuery` list holds its own answer's keys and `useRecords(type, keys)` the keys it was given, so a record a channel's `records` frame adopts reaches neither. The whole-type form is the channel-records counterpart of a live window: `ready` from its first read, every record of the type the store holds (optimistic ones included), default order by key, and none evicted while it is held — a row it alone kept goes when the last reader of the type lets go (#680) |
+| An answer is the SAME object until what it shows moved | `useQuery`, `useRecord` and both `useRecords` forms hand back the previous answer — and its `data` array — while the status and every row object match: a refetch or poll that found the same rows, or a re-read after an unrelated change, re-runs nothing derived from it (Solid's `===`). A whole-type reader with `where` is not even TOLD of a record it neither shows nor would show: on a run page the viewer's alerts list stopped hearing the fleet's runs (180 of 200 frames, 0 its own) |
+| A busy feed is throttled by the reader, `useRecords(type, { throttleMs })` | the first change is told at once, a burst as ONE notification at the end of the period, the last always lands; `release()` drops what is owed. A live board on a phone took ten records a second, each a whole-board redraw: `throttleMs: 1000` tells it 21 times in 20 s instead of 200. Absent or `0`: every change, as before. A non-finite or fractional value is `X_INVARIANT`; `schedule` injects the timer in a test |
 | Knowing THAT records moved is `useRecordChanges(types, listener)` | one call per store update, the moved keys per type, and no hold on any row or type, so a page that re-renders on a channel's `records` pins nothing. `useChannel(...).error()` is the node's refusal of a `failed` membership |
 | Every write is HTTP through core's `clientTransport` | one write path: the action's authz, idempotency and contract; the socket carries none |
 | The answer's records are adopted before the overlay goes | a convergent twin never flickers back to the pre-write value |

package/package.json

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

package/src/record-answer.ts

@@ -0,0 +1,99 @@
+// What a read hook hands back when nothing it shows moved: the SAME answer object. Solid compares a
+// memo's value with `===`, so a fresh array of the same rows re-ran every derivation below it — a
+// panel had to diff rows by hand (`stableRuns`, `sameData`) to keep a board still. And how often a
+// hook may tell its readers at all: `throttleMs`, the first change at once, a burst as one.
+
+import type { AsyncState } from '@ultimat3/core/page';
+import { finiteCount } from '@ultimat3/core/page';
+import { type Scheduler, timeoutScheduler } from './thundering-herd';
+
+/** Same length, same row OBJECTS in the same order. The store keeps an unmoved row's object. */
+export function sameRows<R>(a: readonly R[], b: readonly R[]): boolean {
+  if (a === b) return true;
+  if (a.length !== b.length) return false;
+  for (let index = 0; index < a.length; index++) if (a[index] !== b[index]) return false;
+  return true;
+}
+
+/**
+ * The rows to answer with: the previous answer's own array when it holds exactly these rows, so a
+ * re-read that found nothing new (a poll, a refetch, a change to a row the list does not show)
+ * hands every reader the value it already holds.
+ */
+export function keptRows<R>(previous: AsyncState<readonly R[]> | null, rows: readonly R[]) {
+  const held = previous !== null && 'data' in previous ? previous.data : undefined;
+  return held !== undefined && sameRows(held, rows) ? held : rows;
+}
+
+/** `{ status, data }`, reusing `previous` when both match — the identity a renderer stops on. */
+export function keptAnswer<R>(
+  previous: AsyncState<readonly R[]> | null,
+  status: 'ready' | 'refreshing',
+  rows: readonly R[],
+): AsyncState<readonly R[]> {
+  const data = keptRows(previous, rows);
+  if (
+    previous !== null &&
+    previous.status === status &&
+    'data' in previous &&
+    previous.data === data
+  )
+    return previous;
+  return { status, data };
+}
+
+export interface Notifier {
+  /** A change readers should hear: now, or at the end of the open period. */
+  readonly call: () => void;
+  /** The hook let go: an owed notification is dropped with it. */
+  readonly cancel: () => void;
+}
+
+/**
+ * `notify` at most once per `ms`: a change with no period open is told AT ONCE (a lone update is
+ * never delayed) and opens one; changes inside it are told ONCE at its end, which opens the next.
+ * The last change always lands. No clock: the scheduler's timer is the period. `0` or absent: every
+ * change, synchronously — what a hook did before the option existed.
+ */
+export function throttledNotify(
+  notify: () => void,
+  ms: number | undefined,
+  schedule: Scheduler = timeoutScheduler,
+): Notifier {
+  if (ms === undefined || finiteCount('useRecords', 'throttleMs', ms) === 0) {
+    return { call: notify, cancel: () => undefined };
+  }
+  let cancelTimer: (() => void) | null = null;
+  let owed = false;
+  /** Released: nothing is armed or told again, whatever a notification's reader did meanwhile. */
+  let closed = false;
+  // The period is armed BEFORE the readers hear: a reader that releases the hook while it is told
+  // cancels this timer, rather than the hook arming one after its own release.
+  const open = (): void => {
+    if (closed) return;
+    cancelTimer = schedule(() => {
+      cancelTimer = null;
+      if (!owed || closed) return;
+      owed = false;
+      open();
+      notify();
+    }, ms);
+  };
+  return {
+    call: () => {
+      if (closed) return;
+      if (cancelTimer !== null) {
+        owed = true;
+        return;
+      }
+      open();
+      notify();
+    },
+    cancel: () => {
+      closed = true;
+      cancelTimer?.();
+      cancelTimer = null;
+      owed = false;
+    },
+  };
+}

package/src/record-store.ts

@@ -81,8 +81,8 @@ export class RecordStore implements RecordSink {
       seen.add(rk);
       if (row !== null) out.push([rk.slice(prefix.length), row]);
     }
-    for (const [rk, row] of this.#synced.entries()) {
-      if (rk.startsWith(prefix) && !seen.has(rk)) out.push([rk.slice(prefix.length), row]);
+    for (const [rk, row] of this.#synced.ofType(type)) {
+      if (!seen.has(rk)) out.push([rk.slice(prefix.length), row]);
     }
     return out;
   }
@@ -133,7 +133,7 @@ export class RecordStore implements RecordSink {
       for (const [key, row] of Object.entries(rows)) {
         const rk = recordKey(type, key);
         if (!isRow(row) || key === '') continue;
-        if (this.#synced.restore(rk, row)) this.#touchSynced(rk);
+        if (this.#synced.restore(rk, row, type)) this.#touchSynced(rk);
       }
     });
   }
@@ -141,7 +141,7 @@ export class RecordStore implements RecordSink {
   /** One server write, merged column by column (`SyncedLayer.merge`). */
   merge(type: string, key: string, columns: Row): Row {
     const rk = recordKey(type, key);
-    const { row, changed } = this.#synced.merge(rk, columns);
+    const { row, changed } = this.#synced.merge(rk, columns, type);
     if (changed) {
       this.#touchSynced(rk);
     } else if (this.#overlays.size > 0) {

package/src/record-synced.ts

@@ -15,6 +15,16 @@ export class SyncedLayer {
   readonly #spared = new Map<string, Set<RecordKey>>();
   /** Keys restored from disk and not yet confirmed: the first server row REPLACES, never merges. */
   readonly #provisional = new Set<RecordKey>();
+  /**
+   * Per type, its keys: a whole-type read walks its own rows, never every row of every type. A
+   * run page holds the fleet's runs beside one run's events, and each event reader scanned both.
+   */
+  readonly #byType = new Map<string, Set<RecordKey>>();
+  /**
+   * Each indexed key's type, as its writer NAMED it. Never recovered from the key: a type may hold
+   * a colon (`?query:<name>`, an unnamed live query's rows), so `type:key` splits two ways.
+   */
+  readonly #typeOfKey = new Map<RecordKey, string>();
 
   get(rk: RecordKey): Row | undefined {
     return this.#rows.get(rk);
@@ -34,8 +44,12 @@ export class SyncedLayer {
 
   /** Every row of one type — what a replay's `tx.<type>.all()` reads under the overlay. */
   ofType(type: string): readonly [RecordKey, Row][] {
-    const prefix = `${type}:`;
-    return [...this.#rows].filter(([rk]) => rk.startsWith(prefix));
+    const out: [RecordKey, Row][] = [];
+    for (const rk of this.#byType.get(type) ?? []) {
+      const row = this.#rows.get(rk);
+      if (row !== undefined) out.push([rk, row]);
+    }
+    return out;
   }
 
   isProvisional(rk: RecordKey): boolean {
@@ -49,7 +63,11 @@ export class SyncedLayer {
    * 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 } {
+  merge(
+    rk: RecordKey,
+    columns: Row,
+    type: string,
+  ): { readonly row: Row; readonly changed: boolean } {
     // A restored row is a guess from disk: the server's first answer is the whole truth.
     const current = this.#provisional.delete(rk) ? undefined : this.#rows.get(rk);
     const next: Record<string, unknown> = { ...current };
@@ -62,19 +80,20 @@ export class SyncedLayer {
     }
     if (!changed && current !== undefined) return { row: current, changed: false };
     const row = Object.freeze(next);
-    this.#rows.set(rk, row);
+    this.#put(rk, row, type);
     return { row, changed: true };
   }
 
   /** A conflict policy's verdict replacing the server row outright. */
   set(rk: RecordKey, row: Row): void {
-    this.#rows.set(rk, Object.freeze({ ...row }));
+    // Only ever over a row the server already holds: its type was named when it arrived.
+    this.#put(rk, Object.freeze({ ...row }), this.#typeOfKey.get(rk) ?? typeOf(rk));
   }
 
   /** A row from disk, only where the server has not answered. Answers whether it went in. */
-  restore(rk: RecordKey, row: Row): boolean {
+  restore(rk: RecordKey, row: Row, type: string): boolean {
     if (this.#rows.has(rk)) return false;
-    this.#rows.set(rk, Object.freeze({ ...row }));
+    this.#put(rk, Object.freeze({ ...row }), type);
     this.#provisional.add(rk);
     return true;
   }
@@ -83,7 +102,12 @@ export class SyncedLayer {
   remove(rk: RecordKey): boolean {
     this.#provisional.delete(rk);
     // Gone is no longer spared: a row the server sends again later is a new arrival, not this one.
-    this.#spared.get(rk.slice(0, rk.indexOf(':')))?.delete(rk);
+    const type = this.#typeOfKey.get(rk) ?? typeOf(rk);
+    this.#typeOfKey.delete(rk);
+    this.#spared.get(type)?.delete(rk);
+    const keys = this.#byType.get(type);
+    keys?.delete(rk);
+    if (keys?.size === 0) this.#byType.delete(type);
     return this.#rows.delete(rk);
   }
 
@@ -103,7 +127,7 @@ export class SyncedLayer {
       return false;
     }
     this.#holds.delete(rk);
-    const type = rk.slice(0, rk.indexOf(':'));
+    const type = this.#typeOfKey.get(rk) ?? typeOf(rk);
     if (this.#typeHolds.has(type)) {
       const spared = this.#spared.get(type) ?? new Set<RecordKey>();
       spared.add(rk);
@@ -140,7 +164,22 @@ export class SyncedLayer {
 
   clear(): void {
     this.#rows.clear();
+    this.#byType.clear();
+    this.#typeOfKey.clear();
     this.#provisional.clear();
     this.#spared.clear();
   }
+
+  #put(rk: RecordKey, row: Row, type: string): void {
+    if (!this.#typeOfKey.has(rk)) {
+      this.#typeOfKey.set(rk, type);
+      const keys = this.#byType.get(type);
+      if (keys === undefined) this.#byType.set(type, new Set([rk]));
+      else keys.add(rk);
+    }
+    this.#rows.set(rk, row);
+  }
 }
+
+/** A key's type when no writer named it (a hold on a row not yet there): before its first `:`. */
+const typeOf = (rk: RecordKey): string => rk.slice(0, rk.indexOf(':'));

package/src/use-query.ts

@@ -8,6 +8,7 @@ import type { LiveHandle } from './client-contract';
 import type { JsonValue } from './json';
 import { installedPage, type PageServices } from './page-store';
 import { isServerRender, signalFor } from './reactivity';
+import { keptAnswer } from './record-answer';
 import { type RecordStore, recordKey } from './record-store';
 
 /**
@@ -88,16 +89,17 @@ function liveAccessor<R extends object>(
     if (handle.state() === 'live') seen = true;
     bump();
   });
+  /** The last answer handed out: the same rows back keep its `data` array (`keptAnswer`). */
+  let answer: AsyncState<readonly R[]> | null = null;
   const read = (): AsyncState<readonly R[]> => {
     version();
     const state = handle.state();
     if (state === 'failed') return { status: 'failed', error: handle.error() };
-    if (state === 'live') {
-      seen = true;
-      return { status: 'ready', data: handle.rows() };
-    }
+    if (state === 'live') seen = true;
     // Loading, stale or offline: what was shown stays shown, marked busy — never torn down.
-    return seen ? { status: 'refreshing', data: handle.rows() } : PENDING;
+    else if (!seen) return PENDING;
+    answer = keptAnswer(answer, state === 'live' ? 'ready' : 'refreshing', handle.rows());
+    return answer;
   };
   const release = (): void => {
     off();
@@ -226,14 +228,17 @@ function readAccessor<R extends object>(
   };
 
   load();
+  /**
+   * The last answer handed out: a re-read that answered the same rows (a poll, a refetch, a return
+   * to the tab) hands back its `data` array, so nothing derived from it runs again.
+   */
+  let answer: AsyncState<readonly R[]> | null = null;
   const read = (): AsyncState<readonly R[]> => {
     version();
     if (state.status === 'pending' || state.status === 'failed') return state;
     // Rows are typed by the caller's query; the store holds them as JSON rows.
-    const data = rows() as readonly R[];
-    return state.status === 'refreshing'
-      ? { status: 'refreshing', data }
-      : { status: 'ready', data };
+    answer = keptAnswer(answer, state.status, rows() as readonly R[]);
+    return answer;
   };
   const release = (): void => {
     if (released) return;

package/src/use-record.ts

@@ -6,7 +6,9 @@
 import type { AsyncState, Row } from '@ultimat3/core/page';
 import { pageStore } from './page-store';
 import { isServerRender, signalFor } from './reactivity';
-import { type RecordStore, recordKey } from './record-store';
+import { keptAnswer, throttledNotify } from './record-answer';
+import { type RecordKey, type RecordStore, recordKey } from './record-store';
+import type { Scheduler } from './thundering-herd';
 
 /**
  * A callable `AsyncState`: `pending` until the record first arrives, `ready` from then on —
@@ -43,12 +45,16 @@ export function useRecord<R extends object = Row>(type: string, key: string): Re
     if (store.peek(type, key) !== undefined) seen = true;
     setVersion(version() + 1);
   });
+  let answer: AsyncState<R | undefined> = PENDING;
   const read = (): AsyncState<R | undefined> => {
     version();
     // The store holds JSON rows; the caller names the entity row type it reads them as.
     const row = store.peek(type, key) as R | undefined;
     if (row !== undefined) seen = true;
-    return row === undefined && !seen ? PENDING : { status: 'ready', data: row };
+    if (row === undefined && !seen) return PENDING;
+    // The same row object back is the same answer: nothing reading it runs again.
+    if (answer.status !== 'ready' || answer.data !== row) answer = { status: 'ready', data: row };
+    return answer;
   };
   let held = true;
   const release = (): void => {
@@ -75,6 +81,14 @@ export interface RecordSelection<R extends object = Row> {
   readonly where?: (record: R) => boolean;
   /** Absent: by record key, ascending — creation order for a uuid v7 key. */
   readonly order?: (a: R, b: R) => number;
+  /**
+   * Tell readers at most once per this many ms: the first change at once, a burst as ONE change at
+   * the end of the period, the last always landing. For a projection a busy feed moves many times
+   * a second (a live board on a phone). Absent or `0`: every change, as it lands.
+   */
+  readonly throttleMs?: number;
+  /** The period's timer. Defaults to `setTimeout`; a test injects its own. */
+  readonly schedule?: Scheduler;
 }
 
 /**
@@ -131,16 +145,22 @@ function byKeys<R extends object>(
     for (const key of keys) store.retain(type, key);
   });
   let seen = present().length > 0;
+  let answer: AsyncState<readonly R[]> | null = null;
   const unsubscribe = store.subscribe((changed) => {
-    if (![...changed].some((key) => targets.has(key))) return;
-    if (present().length > 0) seen = true;
-    bump();
+    for (const rk of changed) {
+      if (!targets.has(rk)) continue;
+      if (present().length > 0) seen = true;
+      bump();
+      return;
+    }
   });
   const read = (): AsyncState<readonly R[]> => {
     version();
     const rows = present();
     if (rows.length > 0) seen = true;
-    return !seen ? PENDING : { status: 'ready', data: rows };
+    if (!seen) return PENDING;
+    answer = keptAnswer(answer, 'ready', rows);
+    return answer;
   };
   let held = true;
   const release = (): void => {
@@ -163,15 +183,36 @@ function ofType<R extends object>(
 ): RecordsAccessor<R> {
   const prefix = `${type}:`;
   const { where, order } = selection;
+  const notify = throttledNotify(bump, selection.throttleMs, selection.schedule);
   store.retainType(type);
   // Recomputed once per change to this type, never per read: the same answer back is what tells
   // a fine-grained renderer nothing moved.
   let answer: AsyncState<readonly R[]> | null = null;
   let answered = -1;
+  /** The keys the current answer shows: a change to one of them moves it, whatever `where` says. */
+  let shown: ReadonlySet<RecordKey> = new Set();
+  /**
+   * Whether `rk` can move the answer readers hold: shown in it, or kept by `where` now. A record of
+   * the type the list neither shows nor would show — the fleet's run beside one viewer's — is
+   * nobody's change here, and told to nobody (a stale answer is told regardless: it is re-read).
+   */
+  const moves = (rk: RecordKey): boolean => {
+    if (where === undefined || answer === null || answered !== version() || shown.has(rk)) {
+      return true;
+    }
+    // The store holds JSON rows; the caller names the entity row type it reads them as.
+    const row = store.peek(type, rk.slice(prefix.length)) as R | undefined;
+    try {
+      return row !== undefined && where(row);
+    } catch {
+      // The read raises it to the caller; a listener that threw would silence the page's others.
+      return true;
+    }
+  };
   const unsubscribe = store.subscribe((changed) => {
     for (const rk of changed) {
-      if (!rk.startsWith(prefix)) continue;
-      bump();
+      if (!rk.startsWith(prefix) || !moves(rk)) continue;
+      notify.call();
       return;
     }
   });
@@ -181,11 +222,15 @@ function ofType<R extends object>(
     // The store holds JSON rows; the caller names the entity row type it reads them as.
     const keyed = store.keyed(type) as readonly (readonly [string, R])[];
     const kept = where === undefined ? [...keyed] : keyed.filter(([, row]) => where(row));
-    const rows =
-      order === undefined
-        ? kept.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([, row]) => row)
-        : kept.map(([, row]) => row).sort(order);
-    answer = { status: 'ready', data: rows };
+    if (order === undefined) kept.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    else kept.sort(([, a], [, b]) => order(a, b));
+    // Only a `where` asks what is shown: with none, every record of the type moves the answer.
+    if (where !== undefined) shown = new Set(kept.map(([key]) => `${prefix}${key}`));
+    answer = keptAnswer(
+      answer,
+      'ready',
+      kept.map(([, row]) => row),
+    );
     answered = at;
     return answer;
   };
@@ -193,6 +238,7 @@ function ofType<R extends object>(
   const release = (): void => {
     if (!held) return;
     held = false;
+    notify.cancel();
     unsubscribe();
     store.releaseType(type);
   };