@ultimat3/realtime 29.4.0 → 30.1.0

package/src/query-window.ts

@@ -2,6 +2,7 @@
 // read once for N subscribers, and how one that is known to be wrong is replaced. The authz
 // decision is never here — `live-query.ts` owns that, once per subscriber, over what this returns.
 
+import type { LiveReadPhase } from '@ultimat3/query';
 import { WindowReadTimeoutError } from './errors';
 import type { JsonValue, Row } from './json';
 import type { LiveQueryDefinition, LiveSubscription, SnapshotResult } from './live-contract';
@@ -64,10 +65,16 @@ export interface QueryEntry {
    * can answer: a definition with no lsn provider returns `''` from every snapshot.
    */
   generation: number;
-  /** The generation of the newest read whose rows are in `rows`. `0` before the first one lands. */
+  /** The newest read settled into `rows`, or discarded as behind them. `0` before the first. */
   applied: number;
   readonly readDeadlineMs: number;
   readonly schedule: Scheduler;
+  /**
+   * The newest subscriber's `traceparent`, raw (`noteTraceparent`). A subscribe's read is that
+   * trace's child; a re-run a change forced LINKS to it. One per window, because the read is: N
+   * subscribers share one read, and it can parent on one trace only.
+   */
+  traceparent: string | null;
 }
 
 /**
@@ -119,9 +126,24 @@ export function queryEntry(
     applied: 0,
     readDeadlineMs: usableDeadline(options?.readDeadlineMs),
     schedule: options?.schedule ?? timeoutScheduler,
+    traceparent: null,
   };
 }
 
+/**
+ * Remember the subscriber's `traceparent` for the window's next read. Bounded and never parsed
+ * here: a value is either a string a W3C header could be or it is dropped, and `traceLiveRead`
+ * ignores one that does not parse — telemetry never fails a subscribe.
+ */
+export function noteTraceparent(entry: QueryEntry, traceparent: string | null | undefined): void {
+  if (typeof traceparent === 'string' && traceparent.length <= TRACEPARENT_MAX) {
+    entry.traceparent = traceparent;
+  }
+}
+
+/** `00-<32>-<16>-<2>` is 55 characters; anything far past it is not one. */
+const TRACEPARENT_MAX = 128;
+
 /**
  * The window this subscriber is served from, read once per entry. A subscriber arriving while
  * another's read is in flight joins that read rather than issuing its own — N cold subscribers on
@@ -137,7 +159,7 @@ export async function fillWindow(entry: QueryEntry): Promise<FilledWindow> {
     // Read before `startRead` clears it: a second caller arriving during the read joins it and is
     // not the one that forced it, which is what keeps one forced read from becoming N.
     const forced = entry.stale;
-    const pending = forced || entry.reading === null ? startRead(entry) : entry.reading;
+    const pending = forced || entry.reading === null ? startRead(entry, 'snapshot') : entry.reading;
     const result = await pending.result;
     const again = await entry.lock.run(async () => {
       // Two rules, and neither can stand in for the other. Against another READ it is identity —
@@ -156,6 +178,10 @@ export async function fillWindow(entry: QueryEntry): Promise<FilledWindow> {
         applyRead(entry, pending, result);
         // A forced read outranks a first one: what it replaced was known to be wrong.
         landed = forced || landed === 'forced' ? 'forced' : first ? 'first' : landed;
+      } else if (isNewestRead(entry, pending)) {
+        // Discarded: the window is already past this answer. Settled all the same, or `applied`
+        // reads as a read still out and no repair ever trusts this window again.
+        entry.applied = pending.generation;
       }
       // A change reached this window while its first read was in flight and could not be folded,
       // so what just landed may predate it: read once more before serving anyone a partial window.
@@ -189,7 +215,8 @@ const COLD_REREADS = 3;
  * that repairs a stale window mid-fanout is spelled here rather than deadlocking on the other.
  */
 export async function refillWindowInLane(entry: QueryEntry): Promise<void> {
-  const pending = startRead(entry);
+  // A change asked for this read, not a subscriber: it links to the window's trace (`rerun`).
+  const pending = startRead(entry, 'rerun');
   const result = await pending.result;
   // Same identity rule as `fillWindow`: a read issued before this one may still be in flight, and
   // whichever was issued LAST is the one the window keeps.
@@ -219,13 +246,13 @@ function usableDeadline(declared: number | undefined): number {
  * otherwise would be a second, false promise — so the abandoned read runs to completion with
  * nobody listening, and the next caller issues its own instead of joining a corpse.
  */
-function startRead(entry: QueryEntry): PendingRead {
+function startRead(entry: QueryEntry, phase: LiveReadPhase): PendingRead {
   // Cleared here rather than when the read lands: the read about to be issued is the one that
   // answers the staleness, so a second caller must join it instead of forcing another.
   entry.stale = false;
   entry.generation += 1;
 
-  const read = readSnapshot(entry);
+  const read = readSnapshot(entry, phase);
   let expire: () => void = noop;
   const deadline = new Promise<never>((_resolve, reject) => {
     // Assigned synchronously — a Promise executor runs before the constructor returns — so `done`
@@ -272,9 +299,14 @@ function startRead(entry: QueryEntry): PendingRead {
  * to prevent is now permanent and silent. `async` so a definition that throws synchronously takes
  * the same path as one that rejects.
  */
-async function readSnapshot(entry: QueryEntry): Promise<SnapshotResult> {
+async function readSnapshot(entry: QueryEntry, phase: LiveReadPhase): Promise<SnapshotResult> {
   try {
-    return await entry.definition.snapshot({ input: entry.input, tenant: entry.tenant });
+    return await entry.definition.snapshot({
+      input: entry.input,
+      tenant: entry.tenant,
+      traceparent: entry.traceparent,
+      phase,
+    });
   } catch (error) {
     entry.stale = true;
     throw error;

package/src/server.ts

@@ -50,6 +50,49 @@ export {
   resetChannelTransport,
   setChannelTransport,
 } from './channel-publish';
+export {
+  type AgentDial,
+  type AgentSocket,
+  type DeviceAgent,
+  type DeviceAgentOptions,
+  deviceAgent,
+} from './device-agent';
+export {
+  DeviceFrameTooLargeError,
+  DeviceOfflineError,
+  DeviceRequestTimeoutError,
+} from './device-errors';
+export {
+  DEVICE_FRAME_QUEUE_MAX,
+  DEVICE_REQUESTS_OUTSTANDING_MAX,
+  type DeviceFrameHandler,
+  type DeviceInfo,
+  type DeviceWs,
+} from './device-host';
+export {
+  beginDeviceSocketGeneration,
+  DEFAULT_DEVICE_HEARTBEAT_MS,
+  DEFAULT_DEVICE_REQUEST_DEADLINE_MS,
+  DEFAULT_DEVICE_SOCKETS_PER_ACTOR,
+  DEVICE_AUTH_DEADLINE_MS,
+  DEVICE_MAX_PENDING_UPGRADES,
+  type DeviceAttachment,
+  type DeviceAttachOptions,
+  type DeviceRequestOptions,
+  type DeviceSocket,
+  type DeviceSocketOptions,
+  declaredDeviceSockets,
+  deviceSocket,
+  forgetDeviceSockets,
+} from './device-socket';
+export type {
+  DeviceGrant,
+  DeviceTokenResolver,
+  DeviceUpgradeFacts,
+  DeviceUpgradeTarget,
+  DeviceWsData,
+} from './device-upgrade';
+export { DEVICE_FRAME_MAX_BYTES } from './device-wire';
 export { RealtimeTopologyError } from './errors';
 export {
   InProcessTransport,

package/src/socket.ts

@@ -199,7 +199,7 @@ export class SyncSocket {
    * 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
+   * was deemed current forever, and `update-available` never came. Measured on one adopter: 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.
    */

package/src/sync-frames.ts

@@ -76,6 +76,13 @@ export function frameRouter(options: FrameRouterOptions): FrameRouter {
         ? await presence.roster(name)
         : await presence.join(name, { id: socket.id, actorId: socket.actorId });
     if (presence) options.busAnswered?.();
+    // Asked after the awaits, because the race IS the awaits: `teardown` ran during the beat, the
+    // beat answered false, and the `join` above wrote a member no close will ever remove — a ghost
+    // on every other client's roster until the TTL. Taken back here, by this write's own author.
+    if (presence && socket.closed) {
+      await presence.leave(name, socket.id);
+      return;
+    }
     // Read, though nothing here can repair it: the next beat re-sends the set, and the log is the
     // only trace a dropped one leaves anywhere.
     if (!socket.send(presenceFrame(name, 'sync', roster.members, roster.total))) {
@@ -184,6 +191,7 @@ export function frameRouter(options: FrameRouterOptions): FrameRouter {
           input: frame.target.input,
           sid: frame.sid,
           cursor: frame.target.cursor,
+          ...(frame.traceparent === undefined ? {} : { traceparent: frame.traceparent }),
         });
         // `subscribe` has already seated the subscription and cleared its desync mark, so a reply
         // the socket refuses leaves the server believing a client that holds no rows is in sync:

package/src/sync-node-bounds.ts

@@ -142,3 +142,23 @@ export function clientHeartbeatMs(
   const idleBound = Math.max(1_000, Math.floor(idleTimeoutMs / 4));
   return Math.min(presenceBeatMs ?? DEFAULT_HEARTBEAT_MS, idleBound);
 }
+
+const utf8 = new TextEncoder();
+
+/**
+ * Closes the socket 1009 — Bun's own code for a payload past `maxPayloadLength` — when an
+ * inbound frame is over `maxFrameBytes`, and says so. The node refuses it itself: on a listener a device
+ * socket shares, Bun's limit is the widest mount's, not this node's.
+ */
+export function refusedOverBytes(
+  ws: { close(code: number, reason: string): void },
+  message: string | Uint8Array,
+  limit: number,
+): boolean {
+  const over =
+    typeof message === 'string'
+      ? message.length * 3 > limit && utf8.encode(message).length > limit
+      : message.byteLength > limit;
+  if (over) ws.close(1009, 'frame over maxFrameBytes');
+  return over;
+}

package/src/sync-node.ts

@@ -32,6 +32,7 @@ import { ackRefOf, frameRouter } from './sync-frames';
 import {
   clientHeartbeatMs,
   drainGraceMs,
+  refusedOverBytes,
   socketCeilings,
   syncNodeBounds,
 } from './sync-node-bounds';
@@ -267,6 +268,7 @@ export function syncNode(options: SyncNodeOptions): SyncNode {
     // 120s budget under it decided nothing.
     idling = setInterval(() => {
       for (const socket of sockets.idle()) evict(socket, CLOSE.idle, 'idle timeout');
+      detach(options.registry.repairMarked(), 'sync.repair_sweep');
     }, idleSweepPeriodMs(sockets.idleTimeoutMs));
     idling.unref();
     if (options.authenticate) {
@@ -398,6 +400,8 @@ export function syncNode(options: SyncNodeOptions): SyncNode {
       message(ws: SyncWs, message: string | Uint8Array): void {
         const socket = sockets.get(ws.data.socketId);
         if (!socket) return;
+        // Bun's `maxPayloadLength` is the widest mount's on a shared listener: the bound is ours.
+        if (refusedOverBytes(ws, message, bounds.maxFrameBytes)) return;
         void (async () => {
           // Decoded into a binding the failure path can read: an ack has to name the thing that
           // failed — the mutation key the client's queue holds, the sid its subscription holds —
@@ -428,9 +432,13 @@ export function syncNode(options: SyncNodeOptions): SyncNode {
 
       drain(ws: SyncWs): void {
         // A `records` frame backpressure refused left this socket gapped on that channel; the
-        // repair is the node's verdict, sent the moment the socket can take a frame again.
+        // repair is the node's verdict, sent the moment the socket can take a frame again. A live
+        // query's refused frame is the same debt, and its only other reader is the next change to
+        // that query, which may never come.
         const socket = sockets.get(ws.data.socketId);
-        if (socket) sockets.gapRepairs.repairAll(socket);
+        if (!socket) return;
+        sockets.gapRepairs.repairAll(socket);
+        if (socket.desynced.size > 0) detach(options.registry.repair(socket), 'sync.drain_repair');
       },
 
       close(ws: SyncWs): void {

package/src/sync-origin.ts

@@ -13,7 +13,8 @@ import { type OriginVerdict, proveSameOrigin } from '@ultimat3/core';
  *   declaration IS the app's origin, so it is the whole list: the origin the node sees is derived
  *   from the `Host` header, which names whatever host the request was aimed at — a sibling
  *   subdomain pointed at this node is "its own origin" by that reading, and a `Domain=`-wide
- *   session cookie rides its socket;
+ *   session cookie rides its socket. `sec-fetch-site` is withheld from the rule here for the same
+ *   reason: a browser says `same-origin` of the host it dialled, and that host is the question;
  * - **the node's own ORIGIN, only when nothing is declared** — host and port exactly as the
  *   request reached it (`x dev`, a combined-role container). A host name alone is not this app:
  *   cookies are not isolated by port. `admitReached` keeps it beside a declared list (`x dev`).
@@ -28,10 +29,11 @@ export function upgradeOrigin(
   if (origin === null) return { ok: true };
   // Normalised once (`https://x/` and `https://x` are one origin), then matched as whole strings.
   const admitted = allowedOrigins.map((allowed) => URL.parse(allowed)?.origin);
+  const listIsWhole = admitted.length > 0 && !admitReached;
   return proveSameOrigin({
-    selfOrigins: admitted.length > 0 && !admitReached ? [] : selfOrigins(url),
+    selfOrigins: listIsWhole ? [] : selfOrigins(url),
     origin,
-    secFetchSite: request.headers.get('sec-fetch-site'),
+    secFetchSite: listIsWhole ? null : request.headers.get('sec-fetch-site'),
     listed: (asked) => admitted.includes(asked),
     listName: 'APP_URL or syncNode({ allowedOrigins })',
   });

package/src/sync-protocol.ts

@@ -101,6 +101,13 @@ export interface SubscribeFrame {
   readonly op: 'add' | 'drop';
   readonly sid: string;
   readonly target: SubscribeTarget;
+  /**
+   * The page's W3C `traceparent`, so the snapshot this subscribe causes joins the page's trace.
+   * Optional and **additive**, no `PROTOCOL_VERSION` bump: an old node never reads it, an old
+   * client never sends it. A value that is not a short string is DROPPED, never refused — a
+   * garbage header costs the subscriber its trace, not its subscription.
+   */
+  readonly traceparent?: string;
 }
 
 export interface SnapshotFrame {
@@ -201,6 +208,9 @@ export const FRAME_KINDS: readonly FrameKind[] = [
   'replay-gap',
 ];
 
+/** `00-<32>-<16>-<2>` is 55 characters; past this bound a value is dropped unread. */
+const TRACEPARENT_MAX = 128;
+
 export function encode(frame: Frame): string {
   return JSON.stringify(frame);
 }
@@ -233,14 +243,19 @@ export function decode(raw: string | Uint8Array): Frame {
         ? hello
         : { ...hello, heartbeatMs: num(parsed, 'heartbeatMs') };
     }
-    case 'subscribe':
-      return {
+    case 'subscribe': {
+      const frame = {
         type: 'subscribe',
         v: PROTOCOL_VERSION,
         op: pick(parsed, 'op', ['add', 'drop'] as const),
         sid: str(parsed, 'sid'),
         target: target(parsed['target']),
-      };
+      } as const;
+      const trace = parsed['traceparent'];
+      return typeof trace === 'string' && trace.length <= TRACEPARENT_MAX
+        ? { ...frame, traceparent: trace }
+        : frame;
+    }
     case 'snapshot': {
       const base = {
         type: 'snapshot',

package/src/use-mutation.ts

@@ -4,11 +4,18 @@
 // before the overlay goes — no flicker — and a refusal takes the overlay back. No socket writes.
 
 import type { ConflictPolicy } from '@ultimat3/core/page';
-import { actionPath, isSuperseded, isUltimateError, pageClient, uuidV7 } from '@ultimat3/core/page';
+import {
+  isSuperseded,
+  isUltimateError,
+  pageClient,
+  renderedActionPin,
+  uuidV7,
+} from '@ultimat3/core/page';
 import type { JsonValue } from './json';
 import { knownOffline, type OutboxHandle, peekOutbox } from './outbox-slot';
 import { OfflineQueueAbandonedError, ServerRenderLiveError } from './page-errors';
 import { installedPage, type PageWrites, pageRealtime } from './page-store';
+import { mutationWire } from './pinned-wire';
 import { isServerRender, signalFor } from './reactivity';
 import { carriedBy } from './record-store';
 
@@ -121,6 +128,11 @@ export function useMutation(mutator: MutatorLike): Mutate {
   const call = async (input: JsonValue): Promise<unknown> => {
     if (writes === undefined) throw new ServerRenderLiveError({ operation: 'useMutation()' });
     const page = installedPage('useMutation');
+    // The pin the server stamped into this document, resolved ONCE: the outbox keeps it with the
+    // write, so a replay goes where the write was aimed. Before anything is painted, counted or
+    // queued: an input that cannot fill the pin is no write.
+    const http = renderedActionPin(mutator.name);
+    const wire = mutationWire(mutator.name, input, http);
     const issued = pageClient().scope.epoch;
     const key = `${mutator.name}:${uuidV7()}`;
     const local = mutator.local;
@@ -152,7 +164,12 @@ export function useMutation(mutator: MutatorLike): Mutate {
         if (pageClient().scope.epoch !== issued) {
           throw new OfflineQueueAbandonedError({ name: mutator.name });
         }
-        await outbox.enqueue({ key, name: mutator.name, input });
+        await outbox.enqueue({
+          key,
+          name: mutator.name,
+          input,
+          ...(http === undefined ? {} : { http }),
+        });
       } catch (error) {
         page.store.drop(key);
         // A principal change is nobody's failure to report; a disk that refused the write is.
@@ -196,9 +213,9 @@ export function useMutation(mutator: MutatorLike): Mutate {
     const carried = new Set<string>();
     try {
       output = await page.services.send({
-        method: 'POST',
-        url: actionPath(mutator.name),
-        body: input,
+        method: wire.method,
+        url: wire.url,
+        body: wire.body,
         idempotencyKey: key,
         onEnvelope: (envelope) => carriedBy(envelope, carried),
       });

package/src/use-query.ts

@@ -7,6 +7,7 @@ import { type AsyncState, isSuperseded, type RecordEnvelope, type Row } from '@u
 import type { LiveHandle } from './client-contract';
 import type { JsonValue } from './json';
 import { installedPage, type PageServices } from './page-store';
+import type { QueryPoll } from './query-poll';
 import { isServerRender, signalFor } from './reactivity';
 import { keptAnswer } from './record-answer';
 import { type RecordStore, recordKey } from './record-store';
@@ -30,8 +31,13 @@ export interface QueryRef {
 
 /** A callable `AsyncState` over the list, plus the two things a caller does to it. */
 export type QueryAccessor<R extends object = Row> = (() => AsyncState<readonly R[]>) & {
-  /** Read again from the first page, keeping the current rows on screen (`refreshing`). */
-  refetch(): void;
+  /**
+   * Read again from the first page, keeping the current rows on screen (`refreshing`). Settles
+   * once the answer is on screen or refused — never rejects, so a pull or a button awaits it. A
+   * live read settles at once — its socket is its refresh — unless its subscription was refused:
+   * that one is asked again, and settles on the node's next answer.
+   */
+  refetch(): Promise<void>;
   /**
    * The next page, appended — from the cursor the server's last page answered with. A no-op on a
    * live read, on a read with no `first`, and once the server said there is no next page.
@@ -45,6 +51,7 @@ export type QueryAccessor<R extends object = Row> = (() => AsyncState<readonly R
 
 const PENDING: AsyncState<never> = Object.freeze({ status: 'pending' });
 const nothing = (): void => undefined;
+const settled = (): Promise<void> => Promise.resolve();
 
 /**
  * `input` is read ONCE, at call time: there is no reactive runtime here to re-run it, and a
@@ -53,8 +60,33 @@ const nothing = (): void => undefined;
 export interface QueryOptions {
   /** Read in pages of this many rows (`query.page`); `more()` appends the next. Non-live only. */
   readonly first?: number;
+  /**
+   * `pollEvery(ms)`: re-read (`refetch`) on a timer that a hidden tab and a lost session stop, and
+   * `release` ends. The safety read beside an at-most-once channel. A VALUE and not a number, so
+   * the timer ships only in an island that polls. Non-live only, by type: a live read has its socket.
+   */
+  readonly poll?: QueryPoll;
 }
 
+/** A live read's options: no `poll`, because the socket is its refresh. */
+export type LiveQueryOptions = Omit<QueryOptions, 'poll'> & { readonly poll?: never };
+
+export function useQuery<R extends object = Row>(
+  ref: QueryRef & { readonly live: true },
+  input: JsonValue,
+  options?: LiveQueryOptions,
+): QueryAccessor<R>;
+export function useQuery<R extends object = Row>(
+  ref: QueryRef & { readonly live?: false },
+  input: JsonValue,
+  options?: QueryOptions,
+): QueryAccessor<R>;
+/** A ref whose liveness the type does not know may be live, so it takes no `poll` either. */
+export function useQuery<R extends object = Row>(
+  ref: QueryRef,
+  input: JsonValue,
+  options?: LiveQueryOptions,
+): QueryAccessor<R>;
 export function useQuery<R extends object = Row>(
   ref: QueryRef,
   input: JsonValue,
@@ -63,7 +95,7 @@ export function useQuery<R extends object = Row>(
   const signal = signalFor('useQuery');
   if (isServerRender()) {
     return Object.assign((): AsyncState<readonly R[]> => PENDING, {
-      refetch: nothing,
+      refetch: settled,
       more: nothing,
       hasMore: () => false,
       release: nothing,
@@ -85,10 +117,6 @@ function liveAccessor<R extends object>(
 ): QueryAccessor<R> {
   // Seen once a snapshot landed — read or not — so a drop after it keeps the rows on screen.
   let seen = handle.state() === 'live';
-  const off = handle.onChange(() => {
-    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[]> => {
@@ -101,12 +129,32 @@ function liveAccessor<R extends object>(
     answer = keptAnswer(answer, state === 'live' ? 'ready' : 'refreshing', handle.rows());
     return answer;
   };
+  /** Settled by the next move after a retry — the snapshot, or a second refusal. */
+  let waiting: (() => void)[] = [];
+  const settle = (): void => {
+    const done = waiting;
+    waiting = [];
+    for (const resolve of done) resolve();
+  };
+  const off = handle.onChange(() => {
+    if (handle.state() === 'live') seen = true;
+    bump();
+    if (handle.state() !== 'loading') settle();
+  });
+  // The socket is a live read's refresh — except for a refused subscription on an open socket,
+  // which stays refused until the socket reconnects: that one is asked again, here. A second pull
+  // while the retry is out waits on the same answer.
+  const refetch = (): Promise<void> =>
+    waiting.length > 0 || (handle.state() === 'failed' && handle.retry())
+      ? new Promise((resolve) => waiting.push(resolve))
+      : settled();
   const release = (): void => {
     off();
+    settle();
     handle.unsubscribe();
   };
   return Object.assign(read, {
-    refetch: nothing,
+    refetch,
     more: nothing,
     hasMore: () => false,
     release,
@@ -159,7 +207,8 @@ function readAccessor<R extends object>(
 
   /**
    * One answer: its rows, and — when the server sent the records envelope — the KEYS of this
-   * read's records in answer order (`records[type]`, which `rowsOf` fills first-seen = data order).
+   * read's records in answer order: `order[type]` where the server sent one, because an object
+   * enumerates integer-like keys ascending; `records[type]`'s own key order where it did not.
    * The browser never derives a key: an answer with no records envelope holds its rows itself.
    */
   const fetch = (
@@ -167,8 +216,9 @@ function readAccessor<R extends object>(
   ): Promise<{ rows: readonly Row[]; keys: string[] | null; next?: string | null }> => {
     let keysOf: string[] | null = null;
     const onEnvelope = (envelope: RecordEnvelope): void => {
-      const records = type === undefined ? undefined : envelope.records?.[type];
-      keysOf = records === undefined ? null : Object.keys(records);
+      if (type === undefined) return;
+      const records = envelope.records?.[type];
+      keysOf = records === undefined ? null : [...(envelope.order?.[type] ?? Object.keys(records))];
     };
     const answered = (rows: readonly Row[]) => ({ rows, keys: keysOf });
     if (options.first === undefined) {
@@ -185,11 +235,12 @@ function readAccessor<R extends object>(
     }));
   };
 
-  const load = (append = false): void => {
+  /** Settles when this read's answer is applied or refused — never rejects. */
+  const load = (append = false): Promise<void> => {
     const mine = ++generation;
     if (state.status === 'ready') state = { status: 'refreshing', data: rows() };
     bump();
-    fetch(append).then(
+    return fetch(append).then(
       (answer) => {
         if (released || mine !== generation) return;
         if (answer.next !== undefined) after = answer.next;
@@ -217,17 +268,15 @@ function readAccessor<R extends object>(
         if (released || mine !== generation) return;
         // The page changed principal under this read: its answer was the previous one's, and the
         // store it would have landed in is already empty. Read again, as the new principal.
-        if (isSuperseded(error)) {
-          load();
-          return;
-        }
+        // Returned, so a poll waiting on this read waits on the re-read too.
+        if (isSuperseded(error)) return load();
         state = { status: 'failed', error };
         bump();
       },
     );
   };
 
-  load();
+  void 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.
@@ -240,20 +289,30 @@ function readAccessor<R extends object>(
     answer = keptAnswer(answer, state.status, rows() as readonly R[]);
     return answer;
   };
+  const refetch = (): Promise<void> => {
+    after = null;
+    return load();
+  };
+  // The poll awaits each read, so a slow answer is never overlapped by the next one.
+  // A read that ended `failed` rejects for the poll alone, so `maxMs` backs it off; `load` and
+  // `refetch` keep resolving for everyone else.
+  const stopPoll = options.poll?.start(() =>
+    refetch().then(() => {
+      if (state.status === 'failed') throw state.error;
+    }),
+  );
   const release = (): void => {
     if (released) return;
     released = true;
+    stopPoll?.();
     off();
     hold([]);
     keys = [];
   };
   return Object.assign(read, {
-    refetch: () => {
-      after = null;
-      load();
-    },
+    refetch,
     more: () => {
-      if (after !== null && state.status === 'ready') load(true);
+      if (after !== null && state.status === 'ready') void load(true);
     },
     hasMore: () => {
       version();