@ultimat3/realtime 27.10.1 → 27.10.2

package/package.json

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

package/src/channel-catch-up.ts

@@ -0,0 +1,35 @@
+// A channel's catch-up read, as the page's socket runs it: an ordinary query read whose records the
+// transport does NOT adopt. They come back to the channel book, which adopts them in ONE
+// notification with the frames it held behind the read — the echo of a pending write among them.
+
+import type { RecordEnvelope } from '@ultimat3/core/page';
+import { pageClient } from '@ultimat3/core/page';
+import { queryClientMethodFor } from '@ultimat3/query/client';
+
+/** What a catch-up read answered for the store; `undefined` for a read that answers no records. */
+export interface CatchUpRecords extends Pick<RecordEnvelope, 'records' | 'removed'> {
+  /**
+   * Whether the principal the read was made for is still the page's. The transport fences the read
+   * itself; these rows are adopted later, by the book, so the book asks again at adoption — the
+   * fence `useMutation` keeps on its own POST. Absent: always current.
+   */
+  readonly current?: (() => boolean) | undefined;
+}
+
+export async function catchUpRead(
+  query: string,
+  params: Readonly<Record<string, string>>,
+): Promise<CatchUpRecords | undefined> {
+  const issued = pageClient().scope.epoch;
+  let answered: CatchUpRecords | undefined;
+  await queryClientMethodFor(query, { baseUrl: '' })(params, {
+    adopt: false,
+    onEnvelope: (envelope) => {
+      answered = {
+        ...envelope,
+        current: () => pageClient().scope.epoch === issued,
+      };
+    },
+  });
+  return answered;
+}

package/src/client-channels.ts

@@ -2,6 +2,7 @@
 // per-channel cursor that decides duplicate from new, and the catch-up read a `replay-gap` or a
 // new epoch triggers. `records` frames go to the store and nowhere else; `events` go to handlers.
 
+import type { CatchUpRecords } from './channel-catch-up';
 import { type PresenceEvent, readPresence } from './channel-presence';
 import type { JsonObject } from './json';
 import { carriedBy, type RecordKey } from './record-key';
@@ -35,8 +36,14 @@ export interface ChannelBookDeps {
   readonly store: RecordStore;
   send(frame: SubscribeFrame): void;
   connected(): boolean;
-  /** Re-run the channel's catch-up read; its records land in the store through the transport. */
-  catchUp(query: string, params: Readonly<Record<string, string>>): Promise<unknown>;
+  /**
+   * Re-run the channel's catch-up read and answer its records UNADOPTED (`channel-catch-up.ts`): the
+   * book adopts them in one notification with the frames it held behind the read.
+   */
+  catchUp(
+    query: string,
+    params: Readonly<Record<string, string>>,
+  ): Promise<CatchUpRecords | undefined>;
   report(error: unknown): void;
   /**
    * When a failed catch-up tries again on its own, on the client's reconnect curve. Absent, a
@@ -303,10 +310,14 @@ export class ChannelBook {
     entry.disarm?.();
     entry.disarm = null;
     this.#set(entry, 'catching-up');
-    // Names no write, by decision (O-507, #648, 2026-10-07): a pending write this read already
-    // reflects settles on its own HTTP answer. Reopen only on an observed double paint.
+    // The read names no write (O-507, reopened 2026-10-14 on an observed double paint). FIXED: a
+    // pending write whose echo is HELD behind the read is settled in the same notification as the
+    // read's rows (`#drain`). NOT fixed: an echo that arrives AFTER the read answered (replication
+    // slower than the read's round trip) — the rows are truth under the still-pending twin until
+    // that echo or the write's own answer settles it. Closing it needs the read to name the writes
+    // its snapshot reflects, which is a server-side change (O-507 in full).
     this.#deps.catchUp(entry.catchUp, entry.params).then(
-      () => this.#drain(entry),
+      (answered) => this.#drain(entry, answered),
       (error: unknown) => {
         this.#deps.report(error);
         // NOT live: the frames held behind the read would land over a store it never refreshed.
@@ -326,7 +337,10 @@ export class ChannelBook {
     );
   }
 
-  #drain(entry: Entry): void {
+  #drain(entry: Entry, answered?: CatchUpRecords): void {
+    // Released while the read was out: its rows and frames are a seat nobody holds, and a new hold
+    // of the topic may already hold newer rows. Nothing lands and nothing is re-read.
+    if (this.#byTopic.get(entry.topic) !== entry) return;
     const held = entry.buffered ?? [];
     // A newer epoch arrived while the read was in flight (the node restarted mid-read): the read
     // answered for the OLD one, so it is re-read in the new one, keeping only that epoch's frames.
@@ -335,6 +349,9 @@ export class ChannelBook {
     if (entry.again !== null || newer !== undefined) {
       const epoch = newer?.epoch ?? entry.again?.epoch ?? entry.epoch;
       entry.again = null;
+      // Its rows land now, alone: they are newer than the store's, and a re-read that fails would
+      // otherwise leave the older ones for the whole retry curve. The frames wait for the re-read.
+      this.#adopt(answered);
       entry.buffered = held.filter((frame) => frame.epoch === epoch);
       this.#restart(entry, epoch);
       this.#read(entry);
@@ -343,13 +360,29 @@ export class ChannelBook {
     entry.buffered = null;
     entry.failures = 0;
     const current = [...held].sort((a, b) => a.seq - b.seq);
-    for (const frame of current) {
-      if (entry.contiguous === null) entry.contiguous = frame.seq - 1;
-      this.#apply(entry, frame);
-    }
+    const store = this.#deps.store;
+    // `#adopt` and `#apply` open batches of their own inside this one: `RecordStore.batch` nests,
+    // so the read's rows and every held frame are still ONE notification.
+    store.batch(() => {
+      this.#adopt(answered);
+      for (const frame of current) {
+        if (entry.contiguous === null) entry.contiguous = frame.seq - 1;
+        this.#apply(entry, frame);
+      }
+    });
     if (entry.state === 'catching-up') this.#set(entry, 'live');
   }
 
+  /** A catch-up read's rows, unless the principal it was read for has left (`CatchUpRecords`). */
+  #adopt(answered: CatchUpRecords | undefined): void {
+    if (answered === undefined || answered.current?.() === false) return;
+    const store = this.#deps.store;
+    store.batch(() => {
+      for (const [type, rows] of Object.entries(answered.records ?? {})) store.adopt(type, rows);
+      for (const [type, keys] of Object.entries(answered.removed ?? {})) store.remove(type, keys);
+    });
+  }
+
   #set(entry: Entry, state: ChannelState): void {
     entry.state = state;
     for (const listener of entry.listeners) listener();

package/src/client-contract.ts

@@ -3,6 +3,7 @@
 // shapes without importing the connection lifecycle underneath — and the bytes that come with it.
 
 import type { Clock, Row } from '@ultimat3/core/page';
+import type { CatchUpRecords } from './channel-catch-up';
 import type { LiveCursor } from './cursor';
 import type { LiveState } from './live-rows';
 import type { RecordStore } from './record-store';
@@ -71,8 +72,12 @@ export interface LiveClientOptions {
   /** Where a failure nobody awaits is reported. Defaults to `console.error`. */
   readonly onError?: (error: unknown) => void;
   /**
-   * A channel's catch-up read, re-run on `replay-gap` or a new epoch: the named query, through
-   * core's transport, so its records land in the store. `page-socket.ts` supplies the real one.
+   * A channel's catch-up read, re-run on `replay-gap` or a new epoch: the named query, answering its
+   * records UNADOPTED for the channel book to adopt with the frames held behind the read.
+   * `page-socket.ts` supplies the real one (`channel-catch-up.ts`).
    */
-  readonly catchUp: (query: string, params: Readonly<Record<string, string>>) => Promise<unknown>;
+  readonly catchUp: (
+    query: string,
+    params: Readonly<Record<string, string>>,
+  ) => Promise<CatchUpRecords | undefined>;
 }

package/src/page-socket.ts

@@ -3,7 +3,7 @@
 // the connection lifecycle: a hook reaches it as `services.socket`, off the page object.
 
 import { onRescope, pageClient } from '@ultimat3/core/page';
-import { queryClientMethodFor } from '@ultimat3/query/client';
+import { catchUpRead } from './channel-catch-up';
 import { LiveClient } from './client';
 import { DEFAULT_HEARTBEAT_MS } from './client-heartbeat';
 import { peekOutbox } from './outbox-slot';
@@ -33,8 +33,7 @@ export function pageSocket(hook: string): LiveClient {
     buildId: target.buildId,
     actorId: pageClient().scope.principal ?? null,
     store: page.store,
-    // The channel's catch-up read is an ordinary query read: core's transport adopts its records.
-    catchUp: (query, params) => queryClientMethodFor(query, { baseUrl: '' })(params),
+    catchUp: catchUpRead,
   });
   page.socket = client;
   pageClient().socket = client;