@ultimat3/realtime 21.0.0 → 22.1.0

package/src/subscriber-gate.ts

@@ -54,6 +54,55 @@ export interface GateTarget {
   readonly rows: readonly Row[];
 }
 
+/**
+ * The shared window, indexed ONCE per fan-out rather than searched per subscriber per patch: a
+ * `rows.find` inside the subscriber loop was O(subscribers × window) — 54.6 ms against 0.7 ms at
+ * 1000 subscribers over a 500-row window. `windowIndex` builds it; `filterPatches` builds its own
+ * when a caller passes none.
+ */
+export interface WindowIndex {
+  readonly byId: ReadonlyMap<string, Row>;
+  readonly position: ReadonlyMap<string, number>;
+}
+
+export function windowIndex(rows: readonly Row[]): WindowIndex {
+  const byId = new Map<string, Row>();
+  const position = new Map<string, number>();
+  rows.forEach((row, at) => {
+    byId.set(row.id, row);
+    position.set(row.id, at);
+  });
+  return { byId, position };
+}
+
+/**
+ * What a subscriber holds as a patch list is folded: the cursor's set, plus what this list has
+ * inserted, minus what it has deleted — never a copy of the set per subscriber.
+ */
+class Holding {
+  readonly #base: ReadonlySet<string>;
+  readonly #added = new Set<string>();
+  readonly #removed = new Set<string>();
+
+  constructor(base: ReadonlySet<string>) {
+    this.#base = base;
+  }
+
+  has(id: string): boolean {
+    return this.#added.has(id) || (this.#base.has(id) && !this.#removed.has(id));
+  }
+
+  fold(patch: RowPatch): void {
+    if (patch.op === 'delete') {
+      this.#added.delete(patch.id);
+      this.#removed.add(patch.id);
+    } else if (patch.op === 'insert') {
+      this.#removed.delete(patch.id);
+      this.#added.add(patch.id);
+    }
+  }
+}
+
 export interface SubscriberGateOptions {
   /**
    * `live.rows_denied`. A row an actor's policy refuses is dropped, never sent and never turned
@@ -113,11 +162,16 @@ export class SubscriberGate {
     who: Subscriber,
     patches: readonly RowPatch[],
     held: ReadonlySet<string>,
+    index: WindowIndex = windowIndex(target.rows),
   ): Promise<RowPatch[]> {
     const out: RowPatch[] = [];
+    const holding = new Holding(held);
     for (const patch of patches) {
-      const allowed = await this.patch(target, who, patch, held.has(patch.id));
-      if (allowed !== null) out.push(allowed);
+      const allowed = await this.#decide(target, who, patch, holding.has(patch.id), index);
+      if (allowed === null) continue;
+      const placed = rebase(allowed, holding, target.rows, index);
+      holding.fold(placed);
+      out.push(placed);
     }
     return out;
   }
@@ -128,6 +182,16 @@ export class SubscriberGate {
     who: Subscriber,
     patch: RowPatch,
     holds: boolean,
+  ): Promise<RowPatch | null> {
+    return await this.#decide(target, who, patch, holds, windowIndex(target.rows));
+  }
+
+  async #decide(
+    target: GateTarget,
+    who: Subscriber,
+    patch: RowPatch,
+    holds: boolean,
+    index: WindowIndex,
   ): Promise<RowPatch | null> {
     // A delete carries no row, so there is nothing to put in front of the rule — `holds` IS the
     // decision, the same one the two branches below take for a row a rule has just refused.
@@ -147,7 +211,7 @@ export class SubscriberGate {
       this.#denied(target.qid, who, patch.id);
       return null;
     }
-    const full = target.rows.find((row) => row.id === patch.id);
+    const full = index.byId.get(patch.id);
     // No whole row means no decision to take. An update patch carries the changed columns only, so
     // a rule reading `row.ownerId` on one reads `undefined` and answers as if the row had said so —
     // fail-closed for `=== actor.id`, and a leak for every `!row.private`. It is not a gate that
@@ -218,6 +282,31 @@ const actorIdOf = (who: Subscriber): string | null => (who.actor === null ? null
  * window stopped holding it. Written once so the two paths cannot answer differently: a client left
  * holding the row instead renders a revoked grant until something else reconnects it.
  */
+/**
+ * The patch as this subscriber must read it. `index` was a position in the SHARED, pre-policy
+ * window, and forwarded unchanged it placed the row out of order for anyone who sees fewer rows —
+ * and its size told them how many rows they may not see sit ahead of it. Re-based on the rows ahead
+ * of it that this subscriber holds; dropped from a delete, which the client applies by id. Bounded
+ * by `CURSOR_ID_LIMIT` like `holds` is: a held row past it is not counted.
+ */
+function rebase(
+  patch: RowPatch,
+  holding: Holding,
+  rows: readonly Row[],
+  index: WindowIndex,
+): RowPatch {
+  if (patch.index === undefined) return patch;
+  const { index: _shared, ...rest } = patch;
+  if (patch.op === 'delete' || patch.row === null) return rest;
+  const at = index.position.get(patch.id) ?? patch.index;
+  let local = 0;
+  for (let i = 0; i < at && i < rows.length; i += 1) {
+    const id = rows[i]?.id;
+    if (id !== undefined && id !== patch.id && holding.has(id)) local += 1;
+  }
+  return { ...rest, index: local };
+}
+
 const withdrawn = (patch: RowPatch): RowPatch => ({
   op: 'delete',
   id: patch.id,

package/src/sync-node-contract.ts

@@ -53,6 +53,12 @@ export interface SyncNodeOptions {
    * is a single-tenant node, and `start()` says so in the log.
    */
   readonly authenticate?: SyncAuthenticator;
+  /**
+   * Exact origins a page may open a socket from, besides this node's own host name — the page's
+   * origin when it is served on another host (`SYNC_URL` on a separate domain). Anything else is
+   * refused `X_SOCKET_ORIGIN_REFUSED` before `authenticate` runs.
+   */
+  readonly allowedOrigins?: readonly string[];
   /** How often an expired grant is re-decided. The clock a socket's authority runs on. */
   readonly reauthenticateIntervalMs?: number;
   readonly clock?: Clock;

package/src/sync-node.ts

@@ -11,13 +11,8 @@ import { evictInChunks } from './drain-evictions';
 import { isClientFault } from './errors';
 import type { TransportSubscription } from './fanout';
 import { CHANGE_SUBJECT_ALL, parseEnvelope, SeqGapDetector } from './replicator';
-import {
-  CLOSE,
-  DEFAULT_MAX_BUFFERED_BYTES,
-  idleSweepPeriodMs,
-  SocketRegistry,
-  SyncSocket,
-} from './socket';
+import { CLOSE, DEFAULT_MAX_BUFFERED_BYTES, SocketRegistry, SyncSocket } from './socket';
+import { idleSweepPeriodMs } from './socket-idle';
 import { GrantBook, sweepGrants } from './sync-auth';
 import { ackRefOf, createFrameRouter } from './sync-frames';
 import { drainGraceMs, socketCeilings, syncNodeBounds } from './sync-node-bounds';
@@ -274,6 +269,7 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
           socketCount: () => sockets.count,
           newSocketId: () => uuid(),
           authenticate: options.authenticate,
+          allowedOrigins: options.allowedOrigins,
           onGranted: (socketId, grant) => grants.set(socketId, grant),
           // The other half of recording the grant before the upgrade: an upgrade that never took
           // gets no `close` callback, so this is the only thing that can free its entry.

package/src/sync-origin.ts

@@ -0,0 +1,33 @@
+// Single responsibility: whether a websocket upgrade may carry this app's ambient credential. No
+// CORS applies to a websocket and the session cookie rides it, so without this a page on a sibling
+// host (same-site, so `SameSite=Lax` does not stop it) opened a socket as its visitor. The rule is
+// core's `proveSameOrigin`, the one `@ultimat3/http`'s CSRF check asks too.
+
+import { type OriginVerdict, proveSameOrigin } from '@ultimat3/core';
+
+/**
+ * Admitted, in order:
+ * - **no `Origin`** — RFC 6455 has a browser send one on every handshake, so a dial without it is
+ *   not a browser and no visitor's cookie can be riding it;
+ * - **the node's own host name**, whatever the port or scheme — cookies are not port-isolated, so
+ *   the page on `:3000` dialling the Compose rung's `:3001` is the same credential boundary, and a
+ *   TLS-terminating ingress means the node cannot know the page's scheme;
+ * - otherwise core's rule, with `allowedOrigins` as the exact list (`APP_URL`'s origin, from the
+ *   CLI, when the page is served on another host than the node).
+ */
+export function upgradeOrigin(
+  request: Request,
+  url: URL,
+  allowedOrigins: readonly string[],
+): OriginVerdict {
+  const origin = request.headers.get('origin');
+  if (origin === null) return { ok: true };
+  if (URL.parse(origin)?.hostname === url.hostname) return { ok: true };
+  return proveSameOrigin({
+    selfOrigins: allowedOrigins,
+    origin,
+    secFetchSite: request.headers.get('sec-fetch-site'),
+    listed: () => false,
+    listName: 'APP_URL or createSyncNode({ allowedOrigins })',
+  });
+}

package/src/sync-upgrade.ts

@@ -3,8 +3,13 @@
 // from what the socket then does — the same line `sync-frames.ts` and `sync-listen.ts` already draw.
 
 import { healthzPayload, readyzPayload, reportError } from '@ultimat3/core';
-import { SocketAuthUnavailableError, SocketUnauthenticatedError } from './errors';
+import {
+  SocketAuthUnavailableError,
+  SocketOriginRefusedError,
+  SocketUnauthenticatedError,
+} from './errors';
 import type { SyncAuthenticator, SyncGrant } from './sync-auth';
+import { upgradeOrigin } from './sync-origin';
 import { toWireError } from './sync-protocol';
 import type { AcceptBudget, Rng } from './thundering-herd';
 
@@ -43,6 +48,11 @@ export interface UpgradeDeps {
   socketCount(): number;
   newSocketId(): string;
   readonly authenticate?: SyncAuthenticator | undefined;
+  /**
+   * Exact origins a page may dial from besides the node's own host name — `APP_URL`'s, when the
+   * page is served on another host than the node (`sync-origin.ts`).
+   */
+  readonly allowedOrigins?: readonly string[] | undefined;
   /**
    * Recorded BEFORE `server.upgrade`, because Bun runs `websocket.open` synchronously inside it
    * (measured on bun 1.4.0) and `open` is where the node reads this grant to build the socket's
@@ -79,12 +89,19 @@ export async function handleUpgrade(
     return deps.ready() ? json(payload) : json({ status: 503, body: payload.body });
   }
   if (url.pathname !== deps.path) return new Response('not found', { status: 404 });
-  // The count, not the rate. Shed the same way and with the same delay attached: a client refused
-  // for a full node and one refused for a fast one have the same next move, and the refusal is
-  // decided before `authenticate` so a full node costs no token service call.
-  if (deps.socketCount() >= deps.maxConnections || !deps.ready() || !deps.accept.tryAccept()) {
-    return shed(deps);
-  }
+  // First, and before anything is spent: a foreign page is refused whatever the node's load.
+  const origin = upgradeOrigin(request, url, deps.allowedOrigins ?? []);
+  if (!origin.ok)
+    return wireErrorResponse(403, new SocketOriginRefusedError({ reason: origin.reason }));
+  // The count and readiness. Decided before `authenticate` so a full node costs no token service
+  // call.
+  if (deps.socketCount() >= deps.maxConnections || !deps.ready()) return shed(deps);
+  // The RATE is RESERVED here and REFUNDED on every exit that takes no socket. Reserved first, so a
+  // reconnect herd reaches `authenticate` bounded by the burst — the token service is the first
+  // thing a herd would otherwise flatten. Refunded, because spent-and-kept, one client dialling
+  // with no credential drained the bucket and every signed-in reconnect behind it was shed.
+  if (!deps.accept.tryAccept()) return shed(deps);
+  const refund = (): void => deps.accept.refund();
   let grant: SyncGrant | null = null;
   if (deps.authenticate) {
     try {
@@ -93,6 +110,7 @@ export async function handleUpgrade(
       // A failure is not a denial. The token service timing out must not read to a client as "you
       // may not connect" — it is told to come back, and this node is the one that pages.
       reportError(error, { source: 'realtime', scope: { operation: 'sync.authenticate' } });
+      refund();
       return wireErrorResponse(
         503,
         new SocketAuthUnavailableError({ detail: 'see the node log for the cause' }),
@@ -101,6 +119,7 @@ export async function handleUpgrade(
     // The decision, made before a socket exists: an upgrade is the cheapest thing to refuse and the
     // most expensive thing to take back.
     if (grant === null) {
+      refund();
       return wireErrorResponse(
         401,
         new SocketUnauthenticatedError({ reason: 'authenticate() resolved no actor' }),
@@ -120,8 +139,11 @@ export async function handleUpgrade(
   // sockets as there were parked requests, and `maxConnections` bounded nothing that a herd could
   // reach. Sound because there is no await between this line and `server.upgrade`, and the count
   // moves INSIDE it: Bun runs `websocket.open` synchronously there, which is where `sockets.add`
-  // runs. No second `tryAccept()`: that budget was spent above.
-  if (!deps.ready() || deps.socketCount() >= deps.maxConnections) return shed(deps);
+  // runs.
+  if (!deps.ready() || deps.socketCount() >= deps.maxConnections) {
+    refund();
+    return shed(deps);
+  }
   const data: WsData = {
     socketId: deps.newSocketId(),
     // The node's own id is "not skewed until the hello says so", never "current forever".
@@ -144,10 +166,12 @@ export async function handleUpgrade(
     // failing upgrades left 20 grants. Rethrown untouched — the throw is the operator's diagnosis,
     // and this line owes it the release, not a verdict.
     deps.onUngranted(data.socketId);
+    refund();
     throw error;
   }
   if (!upgraded) {
     deps.onUngranted(data.socketId);
+    refund();
     return new Response('expected websocket', { status: 426 });
   }
   return undefined;

package/src/thundering-herd.ts

@@ -3,12 +3,12 @@
 //
 // Three mechanisms, in the order they fire:
 //   1. drainPlan()    — the draining node assigns each client a distinct delay slot before closing
-//   2. backoffDelay() — the client's own jittered retry, for failures nobody scheduled
+//   2. policyDelay()  — the client's own jittered retry, for failures nobody scheduled
 //   3. AcceptBudget   — the receiving node's token bucket, so recovery sheds instead of collapsing
 
 import {
+  backoffDelay,
   type Clock,
-  backoffDelay as coreBackoffDelay,
   finiteOption,
   type JitterMode,
   type Random,
@@ -59,20 +59,21 @@ export const browserBackoff: BackoffPolicy = {
 };
 
 /**
- * Attempt is 0-BASED. Result is always in `[0, maxMs]`.
+ * A {@link BackoffPolicy} mapped onto `@ultimat3/core`'s `backoffDelay` — the one curve. Attempt is
+ * 1-BASED, core's count: the wait after the first failure is `attempt: 1` and is `baseMs`.
  *
- * The arithmetic is core's, and `attempt + 1` is the WHOLE of the seam: a client counts its first
- * reconnect as attempt 0 and core counts the first wait as attempt 1, so dropping the shift would
- * double every reconnect delay in the framework — silently, and only under the load this file
- * exists to survive. `thundering-herd-core-parity.test.ts` pins the numbers.
+ * Internal to this package and never re-exported from the barrel. Until 22.0.0 `.` exported a
+ * 0-based `backoffDelay` of its own that shifted by one before delegating, which made two counting
+ * conventions under one name — and a caller that passed a 1-based count to it (the channel
+ * catch-up retry did) waited twice as long as it meant to, with no error anywhere.
  */
-export function backoffDelay(
+export function policyDelay(
+  policy: BackoffPolicy,
   attempt: number,
-  policy: BackoffPolicy = defaultBackoff,
   rng: Rng = Math.random,
 ): number {
-  return coreBackoffDelay({
-    attempt: attempt + 1,
+  return backoffDelay({
+    attempt,
     base: policy.baseMs,
     max: policy.maxMs,
     factor: policy.factor,
@@ -187,6 +188,15 @@ export class AcceptBudget {
     return true;
   }
 
+  /**
+   * Hands back a token `tryAccept` reserved for work that took no socket — an upgrade whose
+   * credential was refused, or whose authenticator failed. Never past `burst`.
+   */
+  refund(): void {
+    this.#refill();
+    this.#tokens = Math.min(this.#burst, this.#tokens + 1);
+  }
+
   /** Delay to hand a refused client, jittered so refusals do not re-synchronise the herd. */
   retryAfterMs(rng: Rng = Math.random): number {
     const base = Math.ceil(1000 / this.#perSecond);

package/src/transport-env.ts

@@ -1,20 +1,30 @@
-// Single responsibility: environment → fanout transport. The one place a boot decides whether this
-// process fans changes out inside its own heap or over NATS, so `x dev`, a `sync` container and any
-// custom host resolve it identically. The KV bucket and the presence TTL are decided here too:
+// Single responsibility: `realtime.transport` + environment → fanout transport. The one place a boot
+// decides whether this process fans changes out inside its own heap or over NATS, so `x dev`, a
+// `sync` container and any custom host resolve it identically. The KV bucket and the presence TTL are decided here too:
 // the bucket's whole-stream age limit and `PresenceRegistry`'s TTL are the same number seen from
 // two sides, and a caller that had to pass each one separately could quietly set them apart.
 
-import type { Clock } from '@ultimat3/core';
-import { finiteOption } from '@ultimat3/core';
+import type { Clock, RealtimeConfig } from '@ultimat3/core';
+import { ConfigInvalidError, finiteOption } from '@ultimat3/core';
 import type { Transport } from './fanout';
 import { InProcessTransport } from './fanout';
 import type { NatsConnect } from './nats-client';
 import { assertBucket } from './nats-jetstream';
 import { NatsTransport } from './nats-transport';
 
-/** The keys read here, and nothing else. Named once so docs and tests cannot drift from the code. */
+/**
+ * The keys read here, and nothing else. Named once so docs and tests cannot drift from the code.
+ * `NATS_URL` is the conventional bus variable: read under `transport: 'nats'` when `urlEnv` names
+ * it, and under `'memory'` only to refuse it — see `selectTransport`.
+ */
 export const TRANSPORT_ENV_KEYS = ['NATS_URL', 'NATS_KV_BUCKET'] as const;
 
+/** The two fields of `app.config.ts`'s `realtime` section that decide the bus. */
+export type RealtimeTopology = Pick<RealtimeConfig, 'transport' | 'urlEnv'>;
+
+/** Named in every refusal, so the reader edits the file the decision lives in. */
+const CONFIG_FILE = 'app.config.ts';
+
 /**
  * One bucket per deployment, not per cluster: two apps sharing a nats-server would otherwise share
  * one presence namespace, and a room name that collided would list the other app's members.
@@ -59,13 +69,22 @@ const nonEmpty = (value: string | undefined): string | undefined =>
   value === undefined || value.trim().length === 0 ? undefined : value.trim();
 
 /**
- * No url means the in-process transport — the same "an unset variable means the embedded default"
- * law the db, mail, storage and replication bindings follow. The bucket name is validated here
- * rather than on first connect: a typo'd bucket is a boot that reports a healthy bus and then
- * fails every presence write, which is the failure this whole selector exists to move earlier.
+ * The config decides the transport and the environment supplies its url — never the other way
+ * round. Until 22.0.0 `NATS_URL` alone decided and `realtime.transport` / `realtime.urlEnv` were
+ * read by nothing, so `transport: 'nats'` with the variable unset booted the in-process bus and
+ * reached no other node, with no error on either side. Both mismatches are refused here:
+ *
+ * - `'nats'` with the variable `urlEnv` names unset or blank.
+ * - `'memory'` with a bus url set (`NATS_URL`, or the variable `urlEnv` names). An operator who set
+ *   one expected fanout across nodes; keeping every change in this heap instead is the same silent
+ *   failure seen from the other side, so the two are refused rather than reconciled.
+ *
+ * The bucket name is validated here rather than on first connect: a typo'd bucket is a boot that
+ * reports a healthy bus and then fails every presence write.
  */
 export function selectTransport(
   env: TransportEnvironment,
+  topology: RealtimeTopology,
   options: SelectTransportOptions = {},
 ): TransportSelection {
   const presenceTtlMs = finiteOption(
@@ -73,22 +92,32 @@ export function selectTransport(
     'presenceTtlMs',
     options.presenceTtlMs ?? DEFAULT_PRESENCE_TTL_MS,
   );
-  const url = nonEmpty(env['NATS_URL']);
 
-  if (url === undefined) {
+  if (topology.transport === 'memory') {
+    refuseStrayBusUrl(env, topology);
     const transport = new InProcessTransport(
       options.clock === undefined ? {} : { clock: options.clock },
     );
     return {
       transport,
       mode: 'embedded',
-      detail: 'in-process fanout — set NATS_URL to reach the other nodes',
+      detail: `in-process fanout — set realtime.transport 'nats' in ${CONFIG_FILE} and NATS_URL to reach the other nodes`,
       bucket: null,
       presenceTtlMs,
       connect: () => Promise.resolve(),
     };
   }
 
+  const urlEnv = topology.urlEnv ?? 'NATS_URL';
+  const url = nonEmpty(env[urlEnv]);
+  if (url === undefined) {
+    throw new ConfigInvalidError({
+      cause: `realtime.transport is 'nats' and realtime.urlEnv names ${urlEnv}, which is unset in this process's environment, so no node would be reachable`,
+      fix: `set ${urlEnv} to the nats-server url for every realtime role (web, sync, replicator), or set realtime: { transport: 'memory' } in ${CONFIG_FILE} for a single node`,
+      meta: { key: 'realtime.urlEnv', variable: urlEnv },
+    });
+  }
+
   const bucket = nonEmpty(env['NATS_KV_BUCKET']) ?? DEFAULT_PRESENCE_BUCKET;
   assertBucket(bucket);
   const transport = new NatsTransport({
@@ -101,9 +130,21 @@ export function selectTransport(
   return {
     transport,
     mode: 'external',
-    detail: 'NATS_URL',
+    detail: urlEnv,
     bucket,
     presenceTtlMs,
     connect: () => transport.connect(),
   };
 }
+
+/** `'memory'` with a bus url in the environment: the conflict `selectTransport` refuses. */
+function refuseStrayBusUrl(env: TransportEnvironment, topology: RealtimeTopology): void {
+  const names = topology.urlEnv === undefined ? ['NATS_URL'] : ['NATS_URL', topology.urlEnv];
+  const set = names.find((name) => nonEmpty(env[name]) !== undefined);
+  if (set === undefined) return;
+  throw new ConfigInvalidError({
+    cause: `${set} is set but realtime.transport is 'memory', so this process would fan out in its own heap and reach no other node`,
+    fix: `set realtime: { transport: 'nats', urlEnv: '${set}' } in ${CONFIG_FILE} to use the bus, or unset ${set} for a single node`,
+    meta: { key: 'realtime.transport', variable: set },
+  });
+}

package/src/use-mutation.ts

@@ -134,6 +134,19 @@ export function useMutation(mutator: MutatorLike): Mutate {
       page.store.push(key, (tx) => mutator.local?.(tx, input), mutator.conflict ?? 'server-wins');
     }
     count(writes, mutator.name, 1);
+    // Older writes still wait in the outbox: this one queues BEHIND them rather than overtaking
+    // them over HTTP — a like queued offline and the unlike made once the network was back could
+    // otherwise land swapped. The replay sends the queue in order, this write last, under its key.
+    const queued = peekOutbox();
+    if (queued !== undefined && queued.pending().length > 0) {
+      try {
+        await queued.enqueue({ key, name: mutator.name, input });
+        void queued.replay().catch(() => undefined);
+        return undefined;
+      } finally {
+        count(writes, mutator.name, -1);
+      }
+    }
     let output: unknown;
     /** The records the answer carried, `type:key` — what the overlay may be settled against. */
     const carried = new Set<string>();

package/src/use-query.ts

@@ -161,7 +161,9 @@ function readAccessor<R extends object>(
    * read's records in answer order (`records[type]`, which `rowsOf` fills first-seen = data order).
    * The browser never derives a key: an answer with no records envelope holds its rows itself.
    */
-  const fetch = (append: boolean): Promise<{ rows: readonly Row[]; keys: string[] | null }> => {
+  const fetch = (
+    append: boolean,
+  ): 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];
@@ -173,10 +175,12 @@ function readAccessor<R extends object>(
     }
     const controls =
       append && after !== null ? { first: options.first, after } : { first: options.first };
-    return method.page(input, controls, { onEnvelope }).then((page) => {
-      after = page.hasNextPage ? page.endCursor : null;
-      return answered(page.rows as readonly Row[]);
-    });
+    // The page's cursor travels WITH its rows and is taken only where the rows are: a `more()`
+    // a refetch superseded wrote its cursor here, before the generation check discarded its rows.
+    return method.page(input, controls, { onEnvelope }).then((page) => ({
+      ...answered(page.rows as readonly Row[]),
+      next: page.hasNextPage ? page.endCursor : null,
+    }));
   };
 
   const load = (append = false): void => {
@@ -186,6 +190,7 @@ function readAccessor<R extends object>(
     fetch(append).then(
       (answer) => {
         if (released || mine !== generation) return;
+        if (answer.next !== undefined) after = answer.next;
         if (type === undefined || answer.keys === null) {
           // Not records — no type named, or no envelope: the list holds its own rows.
           own = append ? [...own, ...answer.rows] : answer.rows;