@ultimat3/realtime 25.1.0 → 25.2.0

package/CLAUDE.md

@@ -170,9 +170,9 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **A dropped `records` frame is counted AND repaired**: per-node `seq`/`epoch` per channel; a refused
   frame marks the socket gapped, and the `drain` handler sends `replay-gap`
   (`channel_replay_gaps_total`). The client re-runs `catchUp`, holding frames meanwhile.
-- **A channel is a DECLARATION**: `channel(name, { params, policy, catchUp, records?, events? })`.
-  Deny by default, and `policy` is REQUIRED (`X_CHANNEL_DECLARATION_INVALID`; a public channel says
-  `policy: allow('public')`). Presence rides `events: true` channels.
+- **A channel is a DECLARATION, no primitive** (docs/history/primitive-factories.md):
+  `channel(name, { params, policy, catchUp, records?, events? })`, deny by default; `policy`
+  REQUIRED (`X_CHANNEL_DECLARATION_INVALID`; public: `allow('public')`). Presence: `events`.
 - **A guard that FAILS on re-auth SUSPENDS the seat** (`guardFailures`): kept, silent until a pass.
   A `null` actor on a `row` channel and a tenancy refusal are DENIALS.
 - **A seat is decided for the actor ON the socket when the guard resolves** (`#settle`); a denied
@@ -287,9 +287,9 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **The disk boot is ONE page script (`boot.ts`, `./boot`)**, served at `/_x/page-boot/<hash>.js`
   on a document with the scope tag and a realtime island; it installs the runtime, wipes every other
   principal's stored scope (read at the wipe), then restores. `booted` reads its promise off
-  `globalThis[Symbol.for('ultimate.page-boot')]`. No boot: islands load its chunk.
-- **An island never carries the outbox**: `boot.ts` builds it; `useMutation` and the page socket read
-  it through `outbox-slot.ts` after `page.booted`. No boot ⇒ a refused write is rejected, not queued.
+  `Symbol.for('ultimate.page-boot')`. No boot: islands load its chunk.
+- **An island never carries the outbox**: `boot.ts` builds it; `useMutation`, `useOutbox`, the page socket
+  read it through `outbox-slot.ts` after `page.booted`. No boot ⇒ a refused write is rejected, not queued.
 
 ## Map
 

package/README.md

@@ -84,7 +84,7 @@ class — stay on `.`.
 | wire | `.` | `PROTOCOL_VERSION` (3), `encode`, `decode`, `Frame` |
 | the node | `./server` | `syncNode` / `listenSyncNode` (`sync` role) |
 | a socket's identity | `./server` | `SyncAuthenticator`, `SyncGrant`, `GrantBook`, `sweepGrants`, `DEFAULT_REAUTH_INTERVAL_MS` |
-| hooks | `.` | `useQuery`, `useRecord`, `useRecords` (by key, or a whole type: `RecordSelection`), `useMutation`, `useMutationQueue`, `useConnection`, `useChannel`, `usePresence`, `hasPageSocket`, `installRealtime` |
+| hooks | `.` | `useQuery`, `useRecord`, `useRecords` (by key, or a whole type: `RecordSelection`), `useMutation`, `useMutationQueue`, `useOutbox`, `useConnection`, `useChannel`, `usePresence`, `hasPageSocket`, `installRealtime` |
 | channel records, no replicator | `./server` | `recordPublisher` — an app's committed rows as channel `records`, sequenced per producer ([below](#channel-records-with-no-replicator)) |
 | channels | `.` | `channel`, `channelRef`, `ChannelHandle`, `topic`, `readPresence`, the channel frame types |
 | first paint | `.` | `holdFirstPaint`, `FIRST_PAINT_HOLD_MS` (1 s) — what the island bootstrap awaits before `mount`: the boot's restore and the open outbox, capped (#506) |
@@ -196,6 +196,7 @@ import {
   useConnection,
   useMutation,
   useMutationQueue,
+  useOutbox,
   usePresence,
   useQuery,
   useRecord,
@@ -220,6 +221,7 @@ const runs = useRecords<Run>('runs', {                              // EVERY `ru
 const like = useMutation(LIKE_POST);                                // await like(input); like.pending
 const connection = useConnection();                                 // .offline .online .reconnectAt .updateAvailable
 const writes = useMutationQueue();                                  // .pending .failed
+const outbox = useOutbox();                                         // .size — queued, not yet sent
 const feedChannel = useChannel(orgFeed, { orgId }, { onEvent });   // records → the store; events → onEvent
 const room = usePresence(orgFeed, { orgId });                      // the channel's roster
 ```
@@ -227,7 +229,9 @@ const room = usePresence(orgFeed, { orgId });                      // the channe
 **One socket per origin and principal**: the page's socket lives in a `SharedWorker`
 (`@ultimat3/realtime/sync-worker`, bundled by `x build`) shared by every tab; with no worker the
 same engine runs in-page. Writes that find no network go to the page's outbox — overlay kept — and
-replay over HTTP, under their original idempotency keys, when the socket comes back. The outbox is
+replay over HTTP, under their original idempotency keys, when the socket comes back; `useOutbox().size`
+counts them until the server takes each one, so an island's "sent when you reconnect" notice reads
+the queue itself. The outbox is
 the page boot's (`@ultimat3/realtime/boot`): an island only reads it off the page. On a page the
 CLI renders no boot for (no scope tag, so nothing on it persists) the island's runtime chunk opens
 no outbox, and such a write is refused like any other — rejected, overlay taken back — never held

package/package.json

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

package/src/client-channels.ts

@@ -292,8 +292,8 @@ export class ChannelBook {
     entry.disarm?.();
     entry.disarm = null;
     this.#set(entry, 'catching-up');
-    // Names no write (#507 pt 2: owner O-507, default none) — a pending write this read already
-    // reflects settles on its own HTTP answer. Where a catch-up names its writes, it goes here.
+    // 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.
     this.#deps.catchUp(entry.catchUp, entry.params).then(
       () => this.#drain(entry),
       (error: unknown) => {

package/src/index.ts

@@ -193,6 +193,7 @@ export {
   useMutation,
   useMutationQueue,
 } from './use-mutation';
+export { type OutboxView, useOutbox } from './use-outbox';
 export { type QueryAccessor, type QueryOptions, type QueryRef, useQuery } from './use-query';
 export {
   type RecordAccessor,

package/src/offline-queue.ts

@@ -99,6 +99,9 @@ export class OfflineQueue {
   #epoch = 0;
   /** Set by `abandon`, never cleared: this queue's principal is gone. */
   #abandoned = false;
+  /** Durable writes in progress, and every one ever started: what a `refresh` must not race. */
+  #writing = 0;
+  #written = 0;
 
   private constructor(store: QueueStore, state: QueueState) {
     this.#store = store;
@@ -136,6 +139,42 @@ export class OfflineQueue {
     await this.#reclaimInflight();
   }
 
+  /**
+   * READ-ONLY re-read, safe without the drain lock: another tab queued, sent or refused writes this
+   * one holds a stale copy of. Unlike `reload` it reclaims nothing and claims nothing — an entry
+   * this tab has `inflight` keeps its state, an entry gone from the disk was settled elsewhere.
+   * A read that a write of this tab's raced is retried: its snapshot may predate that write.
+   */
+  async refresh(): Promise<void> {
+    for (let attempt = 0; attempt < 3 && !this.#abandoned; attempt += 1) {
+      const started = this.#written;
+      const state = await this.#store.load();
+      if (this.#abandoned) return;
+      if (this.#writing > 0 || this.#written !== started) continue;
+      this.#adopt(state);
+      return;
+    }
+  }
+
+  #adopt(state: QueueState): void {
+    const onDisk = new Map(state.mutations.map((mutation) => [mutation.key, mutation]));
+    const kept: QueuedMutation[] = [];
+    for (const mutation of this.#mutations) {
+      const disk = onDisk.get(mutation.key);
+      onDisk.delete(mutation.key);
+      // Gone from the disk: another tab's pass settled it. One on THIS tab's wire stays its own.
+      if (disk === undefined && mutation.status !== 'inflight') continue;
+      if (disk !== undefined && mutation.status !== 'inflight') {
+        mutation.status = disk.status;
+        mutation.error = disk.error;
+      }
+      kept.push(mutation);
+    }
+    for (const disk of onDisk.values()) kept.push({ ...disk });
+    this.#mutations = kept;
+    this.#nextSeq = Math.max(this.#nextSeq, state.nextSeq);
+  }
+
   async #reclaimInflight(): Promise<void> {
     const reclaimed = this.#mutations.filter((mutation) => mutation.status === 'inflight');
     for (const mutation of reclaimed) mutation.status = 'pending';
@@ -371,9 +410,13 @@ export class OfflineQueue {
         mutation.error = null;
         sent += 1;
       } catch (error) {
-        mutation.status = 'pending';
-        mutation.error = toQueueError(error);
-        await this.#persist([mutation]);
+        // Settled inside `send` before it threw (the page outbox acks or fails it, then a merge may
+        // raise): writing it back as `pending` would replay what the server already decided.
+        if (this.#mutations.includes(mutation) && statusOf(mutation) !== 'failed') {
+          mutation.status = 'pending';
+          mutation.error = toQueueError(error);
+          await this.#persist([mutation]);
+        }
         return {
           sent,
           collapsed: this.#collapsed,
@@ -407,11 +450,17 @@ export class OfflineQueue {
    */
   async #persist(puts: readonly QueuedMutation[], deletes: readonly string[] = []): Promise<void> {
     if (this.#abandoned) return;
-    await this.#store.write({
-      puts: puts.map((mutation) => ({ ...mutation })),
-      deletes,
-      nextSeq: this.#nextSeq,
-    });
+    this.#writing += 1;
+    this.#written += 1;
+    try {
+      await this.#store.write({
+        puts: puts.map((mutation) => ({ ...mutation })),
+        deletes,
+        nextSeq: this.#nextSeq,
+      });
+    } finally {
+      this.#writing -= 1;
+    }
   }
 }
 

package/src/outbox-slot.ts

@@ -17,6 +17,18 @@ export interface OutboxHandle {
   enqueue(entry: OutboxEntry): Promise<void>;
   replay(): Promise<unknown>;
   pending(): readonly OutboxEntry[];
+  /** Writes not yet taken by the server. `0` until the store has opened. */
+  readonly size: number;
+  /**
+   * `listener` runs whenever `size` may have moved: a write queued, acked or refused, a queue
+   * opened, a principal change. Returns the release.
+   */
+  subscribe(listener: () => void): () => void;
+  /**
+   * Re-reads the durable queue, which another tab of this user may have changed since, and tells
+   * the listeners. What a write asks before deciding to queue behind older writes or to send.
+   */
+  refresh(): Promise<void>;
   /** Settles once the current principal's queue is open. */
   readonly ready: Promise<void>;
 }

package/src/outbox-tabs.ts

@@ -0,0 +1,62 @@
+/**
+ * The page outbox's tie to the origin's other tabs: one `BroadcastChannel`, on which a tab names
+ * the scope whose durable queue it just changed, so every other tab re-reads it. Closed while the
+ * page sits in the back/forward cache (an open channel keeps a page out of it); reopened on return.
+ */
+
+/** One channel per origin; a message is the scope key whose queue moved. */
+export const OUTBOX_CHANNEL = 'ultimate:outbox';
+
+export interface OutboxTabs {
+  /** Tell every other tab that `scope`'s queue changed on disk. */
+  announce(scope: string): void;
+  stop(): void;
+}
+
+/** What this needs of a window: the channel class, when there is one, and the page events. */
+export interface OutboxTabsWindow {
+  readonly BroadcastChannel?: typeof BroadcastChannel;
+  addEventListener(type: string, listener: (event: Event) => void): void;
+  removeEventListener(type: string, listener: (event: Event) => void): void;
+}
+
+/**
+ * `heard(scope)` for every other tab's announcement; `heard(null)` on a page restored from the
+ * back/forward cache, which missed everything sent while it was frozen.
+ */
+export function outboxTabs(
+  win: OutboxTabsWindow,
+  heard: (scope: string | null) => void,
+): OutboxTabs {
+  const Channel = win.BroadcastChannel;
+  const open = (): BroadcastChannel | undefined => {
+    if (Channel === undefined) return undefined;
+    const opened = new Channel(OUTBOX_CHANNEL);
+    opened.onmessage = (event: MessageEvent) => {
+      if (typeof event.data === 'string') heard(event.data);
+    };
+    return opened;
+  };
+  let channel = open();
+  // `pagehide`, not `unload`: it fires for a page entering the back/forward cache too, and a page
+  // holding an open channel is refused by it.
+  const onHide = (): void => {
+    channel?.close();
+    channel = undefined;
+  };
+  const onShow = (event: Event): void => {
+    if (Reflect.get(event, 'persisted') !== true || channel !== undefined) return;
+    channel = open();
+    heard(null);
+  };
+  win.addEventListener('pagehide', onHide);
+  win.addEventListener('pageshow', onShow);
+  return {
+    announce: (scope) => channel?.postMessage(scope),
+    stop() {
+      win.removeEventListener('pagehide', onHide);
+      win.removeEventListener('pageshow', onShow);
+      onHide();
+    },
+  };
+}

package/src/page-outbox.ts

@@ -19,6 +19,7 @@ import { pageLocalStore, scopeKey } from './local-store-idb';
 import type { DrainReport, QueuedMutation, QueueState, QueueStore } from './offline-queue';
 import { memoryQueueStore, OfflineQueue, toQueueError } from './offline-queue';
 import { OUTBOX_KEY, type OutboxEntry, type OutboxHandle, type OutboxHost } from './outbox-slot';
+import { type OutboxTabs, type OutboxTabsWindow, outboxTabs } from './outbox-tabs';
 import { LocalStoreUnavailableError, OfflineQueueAbandonedError } from './page-errors';
 import { peekPageRealtime } from './page-store';
 import { carriedBy } from './record-store';
@@ -29,8 +30,6 @@ export interface PageOutbox extends OutboxHandle {
   enqueue(entry: OutboxEntry): Promise<void>;
   /** Sends everything queued, in order, stopping at the first write the network could not take. */
   replay(): Promise<DrainReport>;
-  /** Writes not yet taken by the server. `0` until the store has opened. */
-  readonly size: number;
   /**
    * Those writes, in queue order — what `useMutation` re-applies as overlays after a reload, so a
    * queued write is ON SCREEN until its replay settles or refuses it. Empty until `ready`.
@@ -62,6 +61,11 @@ export interface OutboxOptions {
    * the write queued and the post it liked missing, and showed the old count.
    */
   readonly beforeEnqueue?: (() => Promise<void>) | undefined;
+  /**
+   * The tie to this origin's other tabs, which share the durable queue: given `heard`, returns how
+   * to announce this tab's own changes. `pageOutbox` passes a `BroadcastChannel`; none, no sync.
+   */
+  readonly tabs?: ((heard: (scope: string | null) => void) => OutboxTabs) | undefined;
   /** Where a disk that refused the queue is said, by code. Default `console.warn`. */
   readonly warn?: ((error: UltimateError) => void) | undefined;
 }
@@ -91,6 +95,38 @@ export function localOutbox(options: OutboxOptions): PageOutbox {
    */
   let epoch = 0;
   const warn = options.warn ?? ((error: UltimateError): void => console.warn(error));
+  /** Re-read the durable queue (read-only) and tell this tab's listeners what it holds now. */
+  const refreshHeld = async (): Promise<void> => {
+    const now = held;
+    if (now === undefined) return;
+    await now.queue.refresh();
+    if (held === now) notify();
+  };
+  const tabs = options.tabs?.((scope) => {
+    // Another principal's queue is another scope's disk; `null` is "re-read whatever is held".
+    if (held === undefined || (scope !== null && scope !== held.scope)) return;
+    refreshHeld().catch((error: unknown) => unavailable('the outbox could not be re-read', error));
+  });
+  /** After this tab changed the disk: every other tab holding that scope re-reads it. */
+  const announce = (scope: string | undefined): void => {
+    if (scope !== undefined) tabs?.announce(scope);
+  };
+  /**
+   * Told whenever the count may have moved. A listener that throws is rethrown on its own task:
+   * reported like any uncaught error, and never the refusal of the write that moved the count.
+   */
+  const listeners = new Set<() => void>();
+  const notify = (): void => {
+    for (const listener of listeners) {
+      try {
+        listener();
+      } catch (error) {
+        queueMicrotask(() => {
+          throw error;
+        });
+      }
+    }
+  };
   const unavailable = (what: string, error: unknown): void =>
     warn(new LocalStoreUnavailableError({ reason: `${what}: ${renderThrowable(error)}` }));
 
@@ -113,6 +149,7 @@ export function localOutbox(options: OutboxOptions): PageOutbox {
     }
     held?.queue.abandon();
     held = { queue, scope };
+    notify();
   };
   let ready = open();
   /** The current principal's queue: `ready` is re-made by a rescope, so it is re-read until still. */
@@ -128,7 +165,7 @@ export function localOutbox(options: OutboxOptions): PageOutbox {
   let again = false;
 
   const deliver =
-    (queue: OfflineQueue) =>
+    ({ queue, scope }: Held) =>
     async (mutation: QueuedMutation): Promise<void> => {
       const carried = new Set<string>();
       try {
@@ -140,6 +177,8 @@ export function localOutbox(options: OutboxOptions): PageOutbox {
         if (kind === 'retryable' || kind === 'retry-after' || queue.abandoned) throw error;
         // Anything else is the server's decision about this write — kept for the UI, never resent.
         await queue.fail(mutation.key, toQueueError(error));
+        notify();
+        announce(scope);
         overlays()?.drop(mutation.key);
         return;
       }
@@ -147,6 +186,8 @@ export function localOutbox(options: OutboxOptions): PageOutbox {
       // gone, and what is on the page now is somebody else's.
       if (queue.abandoned) return;
       await queue.ack(mutation.key);
+      notify();
+      announce(scope);
       const store = overlays();
       try {
         // Exactly as a live write settles: a row the answer did not carry keeps its overlay until
@@ -166,6 +207,7 @@ export function localOutbox(options: OutboxOptions): PageOutbox {
     held?.queue.abandon();
     held = undefined;
     epoch += 1;
+    notify();
     // The single-flight slot is the principal's too: left set, the next principal's trigger JOINED
     // the abandoned pass — handed its report, another principal's key in it — and its own queue
     // was not drained until some later trigger. `settled` only clears a slot that is still its own.
@@ -198,6 +240,8 @@ export function localOutbox(options: OutboxOptions): PageOutbox {
       await options.beforeEnqueue?.().catch(() => undefined);
       // Abandoned meanwhile, it refuses by the same code.
       await mine.queue.enqueue(entry);
+      notify();
+      announce(mine.scope);
     },
     replay: () => {
       // Single flight: a trigger that lands while a replay is running JOINS it. Open, `online`,
@@ -222,8 +266,10 @@ export function localOutbox(options: OutboxOptions): PageOutbox {
         // sent too, and an `inflight` entry — which only a pass holding this lock could have put
         // on the wire, and it is over — goes back to `pending`.
         return await exclusive(`ultimate-outbox:${now.scope ?? 'memory'}`, async () => {
+          // Re-read under the lock: what another tab queued or sent since is this count too.
           await now.queue.reload();
-          return await now.queue.drain(deliver(now.queue));
+          notify();
+          return await now.queue.drain(deliver(now));
         });
       })();
       const settled = (report?: DrainReport): void => {
@@ -246,6 +292,16 @@ export function localOutbox(options: OutboxOptions): PageOutbox {
     },
     pending: () =>
       (held?.queue.pending() ?? []).map(({ key, name, input }) => ({ key, name, input })),
+    refresh: async () => {
+      await current();
+      await refreshHeld();
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
     get ready(): Promise<void> {
       return ready;
     },
@@ -326,9 +382,15 @@ export function pageOutbox(options: Pick<OutboxOptions, 'beforeEnqueue'> = {}):
   const existing = host[OUTBOX_KEY];
   // Only this function writes the slot, so what it holds is always a `PageOutbox`.
   if (existing !== undefined) return existing as PageOutbox;
-  const outbox = localOutbox({ local: pageLocalStore(), beforeEnqueue: options.beforeEnqueue });
+  const browser = Reflect.has(globalThis, 'document');
+  const outbox = localOutbox({
+    local: pageLocalStore(),
+    beforeEnqueue: options.beforeEnqueue,
+    // Every tab of this user shares the durable queue; each re-reads it when another changes it.
+    ...(browser ? { tabs: (heard) => outboxTabs(globalThis as OutboxTabsWindow, heard) } : {}),
+  });
   Object.defineProperty(host, OUTBOX_KEY, { value: outbox, configurable: true });
-  if (Reflect.has(globalThis, 'document')) {
+  if (browser) {
     listenForDrain(outbox);
     if (!knownOffline()) void outbox.replay().catch(() => undefined);
   }

package/src/use-mutation.ts

@@ -155,6 +155,18 @@ export function useMutation(mutator: MutatorLike): Mutate {
         throw error;
       }
     };
+    // Asked of the DURABLE queue, re-read now: another tab of this user may have queued writes this
+    // tab's copy has not heard of yet, and sending past them reorders the user's intent.
+    if (queued !== undefined) {
+      await queued.refresh().catch(() => undefined);
+      // That read is an await: a principal that left meanwhile must not have this write POSTed, or
+      // queued, as the next one. Refused by the code `enqueue` uses for the same departure.
+      if (pageClient().scope.epoch !== issued) {
+        page.store.drop(key);
+        count(writes, mutator.name, -1);
+        throw new OfflineQueueAbandonedError({ name: mutator.name });
+      }
+    }
     if (queued !== undefined && queued.pending().length > 0) {
       try {
         await enqueue(queued);

package/src/use-outbox.ts

@@ -0,0 +1,49 @@
+// The page outbox's count, as a getter a component reads: how many writes wait to be sent. Read
+// off the outbox the boot seated (`outbox-slot.ts`), never built here, so an island asking ships
+// the slot and none of the queue. A server render holds nothing queued.
+
+import { peekOutbox } from './outbox-slot';
+import { installedPage } from './page-store';
+import { isServerRender, signalFor } from './reactivity';
+
+export interface OutboxView extends Disposable {
+  /** Stop listening (Solid: `onCleanup`). The outbox itself stays, and keeps its writes. */
+  release(): void;
+  /** Writes queued and not yet taken by the server; `0` before the boot has opened the outbox. */
+  readonly size: number;
+}
+
+const SERVER_RENDER: OutboxView = Object.freeze({
+  release: (): void => undefined,
+  [Symbol.dispose]: (): void => undefined,
+  size: 0,
+});
+
+export function useOutbox(): OutboxView {
+  const signal = signalFor('useOutbox');
+  if (isServerRender()) return SERVER_RENDER;
+  const page = installedPage('useOutbox');
+  const [version, setVersion] = signal(0);
+  const moved = (): void => setVersion(version() + 1);
+  let unsubscribe: () => void = () => undefined;
+  let released = false;
+  // After the boot: it seats the outbox, and a queue a previous load left is on disk until then.
+  void page.booted.then(() => {
+    const outbox = peekOutbox();
+    if (released || outbox === undefined) return;
+    unsubscribe = outbox.subscribe(moved);
+    moved();
+  });
+  const release = (): void => {
+    released = true;
+    unsubscribe();
+  };
+  return {
+    release,
+    [Symbol.dispose]: release,
+    get size() {
+      version();
+      return peekOutbox()?.size ?? 0;
+    },
+  };
+}