@ultimat3/realtime 24.0.0 → 25.0.0

package/src/errors.ts

@@ -1,43 +1,19 @@
 // Realtime's X_* codes. Every throw in this package goes through one of these classes so
 // the same string renders in the terminal, the browser overlay, and `--json`.
 
-import { isFixShellSafe, registerErrorCodes, renderFixShellArg } from '@ultimat3/core';
+import { isFixShellSafe, renderFixShellArg } from '@ultimat3/core';
+// The owned code list and its titles are `error-titles.ts` — the one module `sideEffects` lists,
+// imported bare here and from the barrel — so this module is side-effect-free and a chunk keeps
+// only the classes it constructs. Re-exported, so every name is still importable from `./errors`.
+import './error-titles';
+import { REALTIME_OWNED_ERROR_CODES } from './error-titles';
 import { RealtimeError } from './realtime-error';
 
-/** Codes this package declares and owns. */
-export const REALTIME_OWNED_ERROR_CODES = [
-  'X_TOPIC_FORBIDDEN',
-  'X_SUBSCRIPTION_LIMIT',
-  'X_SUBSCRIPTION_ID_TAKEN',
-  'X_FRAME_RATE_LIMIT',
-  'X_PROTOCOL_VERSION',
-  'X_CURSOR_STALE',
-  'X_REBASE_CONFLICT',
-  'X_TRANSPORT_UNAVAILABLE',
-  'X_TRANSPORT_PROTOCOL',
-  'X_REPLICATION_PROTOCOL',
-  'X_REPLICATION_FAILED',
-  'X_REPLICATOR_SLOT_HELD',
-  // Retired in 21.0.0 and never thrown since — kept registered, because a shipped code is
-  // forever: a log line from an older build still resolves through `x errors explain`.
-  'X_LIVE_CLIENT_MISSING',
-  'X_QUERY_NOT_SUBSCRIBABLE',
-  'X_REALTIME_UNINSTALLED',
-  'X_SYNC_UNCONFIGURED',
-  'X_RECORD_REJECTED',
-  'X_CHANNEL_DECLARATION_INVALID',
-  'X_LOCAL_STORE_UNAVAILABLE',
-  'X_LIVE_SERVER_RENDER',
-  'X_LIVE_ROW_UNIDENTIFIED',
-  'X_LIVE_QUERY_UNKNOWN',
-  'X_LIVE_REPLICA_IDENTITY',
-  'X_SOCKET_UNAUTHENTICATED',
-  'X_SOCKET_AUTH_UNAVAILABLE',
-  'X_REALTIME_TOPOLOGY',
-  'X_REPLICATION_TLS',
-  'X_SOCKET_ORIGIN_REFUSED',
-  'X_OFFLINE_QUEUE_ABANDONED',
-] as const;
+export {
+  REALTIME_ERROR_TITLES,
+  REALTIME_OWNED_ERROR_CODES,
+  type RealtimeOwnedErrorCode,
+} from './error-titles';
 
 /**
  * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s, and `X_FORBIDDEN` — thrown by the surface denials this
@@ -131,51 +107,8 @@ export const REALTIME_ERROR_CODES = [
   ...REALTIME_BORROWED_ERROR_CODES,
 ] as const;
 
-export type RealtimeOwnedErrorCode = (typeof REALTIME_OWNED_ERROR_CODES)[number];
 export type RealtimeErrorCode = (typeof REALTIME_ERROR_CODES)[number];
 
-export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, string>> = {
-  X_TOPIC_FORBIDDEN: 'the actor may not subscribe to this topic',
-  X_SUBSCRIPTION_LIMIT: 'socket, tenant or node hit its subscription cap',
-  X_SUBSCRIPTION_ID_TAKEN: 'a subscribe frame reused a sid this socket already holds',
-  X_FRAME_RATE_LIMIT: 'one socket sent frames faster than this node will route them',
-  X_PROTOCOL_VERSION: 'client and sync node disagree on the wire protocol',
-  X_CURSOR_STALE: 'the resume LSN is outside the change buffer',
-  X_REBASE_CONFLICT: 'a local mutation could not be rebased',
-  X_TRANSPORT_UNAVAILABLE: 'the fanout bus is unreachable',
-  X_TRANSPORT_PROTOCOL: 'the bus does not speak the protocol this build speaks',
-  X_REPLICATION_PROTOCOL: 'the WAL stream cannot be decoded',
-  X_REPLICATION_FAILED: 'the replication connection was refused',
-  X_REPLICATOR_SLOT_HELD: 'another replicator already owns this database',
-  X_LIVE_CLIENT_MISSING:
-    'retired in 21.0.0 (no LiveClient to register; see X_REALTIME_UNINSTALLED): a realtime hook ran in a browser with no LiveClient registered',
-  X_QUERY_NOT_SUBSCRIBABLE:
-    'retired in 21.0.0 (liveHookFor was deleted; useQuery reads any query): a hook was bound to a query that is not declared live',
-  X_REALTIME_UNINSTALLED: 'a realtime hook ran in an island bundle that never installed realtime',
-  X_SYNC_UNCONFIGURED: 'a live hook needed the page socket and no sync target was configured',
-  X_RECORD_REJECTED: 'a row reached the record store in a shape it cannot hold',
-  X_CHANNEL_DECLARATION_INVALID: 'a channel() declaration cannot route its rows',
-  X_LOCAL_STORE_UNAVAILABLE: "the page's durable store could not open",
-  X_LIVE_SERVER_RENDER: 'a browser-only live operation ran during a server render',
-  X_LIVE_ROW_UNIDENTIFIED: 'a live query returned a row with no id',
-  X_LIVE_QUERY_UNKNOWN: 'no live query is registered under the name a subscribe frame asked for',
-  X_LIVE_REPLICA_IDENTITY: 'a replicated table has no replica identity',
-  X_SOCKET_UNAUTHENTICATED: 'the sync upgrade carried no credential this app accepts',
-  X_SOCKET_AUTH_UNAVAILABLE: 'the sync node could not decide who a connecting socket is',
-  X_REALTIME_TOPOLOGY: 'a sync node boots on a real database with no reachable change feed',
-  X_REPLICATION_TLS: 'the replication connection failed TLS',
-  X_SOCKET_ORIGIN_REFUSED: 'the websocket upgrade came from another origin',
-  X_OFFLINE_QUEUE_ABANDONED: 'a write was queued after its page changed principal',
-};
-
-// One unconditional call, so a second package claiming one of realtime's codes throws
-// X_ERROR_CODE_DUPLICATE instead of losing silently to whichever module imported first.
-registerErrorCodes(
-  Object.fromEntries(
-    Object.entries(REALTIME_ERROR_TITLES).map(([code, title]) => [code, { title }]),
-  ),
-);
-
 export {
   CursorStaleError,
   LocalStoreUnavailableError,
@@ -189,9 +122,9 @@ export {
 } from './page-errors';
 // Re-exported, never re-declared: `RealtimeError` lives in `realtime-error.ts`, the four
 // replication errors in `replication-errors.ts` and the browser-reachable refusals in
-// `page-errors.ts`, so this file is the CODE TABLE plus the server's refusals. Every name is still
-// importable from `./errors`, which is what the `pg-*` modules and the barrel already do; a
-// browser module imports `./page-errors` so it does not load the table.
+// `page-errors.ts`, and the code table in `error-titles.ts`, so this file is the server's refusals.
+// Every name is still importable from `./errors`, which is what the `pg-*` modules and the barrel
+// already do; a browser module imports `./page-errors` so it does not load these classes.
 export { RealtimeError } from './realtime-error';
 export {
   ReplicaIdentityError,
@@ -214,17 +147,19 @@ export class TopicForbiddenError extends RealtimeError {
 }
 
 /**
- * Load shedding, not a crash: a socket, a tenant or this node asked for more than its cap.
+ * Load shedding, not a crash: a socket, a tenant, an actor or this node asked for more than its cap.
  *
  * `knob` is the option that raises it, and it is passed rather than derived because the `node`
  * scope has more than one — a live-query entry ceiling and a channel-topic ceiling are two
- * different numbers on two different objects. The fix names the constructor option, never an
- * `app.config.ts` field: there is none (`docs/architecture/07-realtime-internals.md:244`), and a
- * fix line naming a field that does not exist is an instruction that cannot be followed.
+ * different numbers on two different objects. Every scope but `actor` names a CONSTRUCTOR option:
+ * those have no `app.config.ts` field, and a fix naming a field that does not exist is an
+ * instruction that cannot be followed. The actor cap is the one that is app config —
+ * `realtime.maxSubscriptionsPerActor` — so its fix names that key and that file first, then the
+ * registry option a host that builds its own `LiveQueryRegistry` sets instead.
  */
 export class SubscriptionLimitError extends RealtimeError {
   constructor(args: {
-    scope: 'socket' | 'tenant' | 'node';
+    scope: 'socket' | 'tenant' | 'actor' | 'node';
     id: string;
     limit: number;
     knob?: string;
@@ -233,7 +168,10 @@ export class SubscriptionLimitError extends RealtimeError {
     super({
       code: 'X_SUBSCRIPTION_LIMIT',
       cause: `${args.scope} ${args.id} reached the subscription cap of ${args.limit}`,
-      fix: `raise ${knob} where this sync node is constructed, or unsubscribe unused live queries`,
+      fix:
+        args.scope === 'actor'
+          ? `defineConfig({ realtime: { maxSubscriptionsPerActor: ${args.limit * 2} } })   # in app.config.ts — realtime.maxSubscriptionsPerActor; or maxPerActor on new LiveQueryRegistry({…}) where a host builds its own; or unsubscribe unused live queries`
+          : `raise ${knob} where this sync node is constructed, or unsubscribe unused live queries`,
     });
   }
 }
@@ -251,7 +189,7 @@ export class FrameRateLimitError extends RealtimeError {
     super({
       code: 'X_FRAME_RATE_LIMIT',
       cause: `socket ${args.socketId} exceeded ${args.perSecond} frames per second`,
-      fix: 'batch subscribes into one frame per subscription and retry after the delay, or raise maxFramesPerSecond where createSyncNode() is called',
+      fix: 'batch subscribes into one frame per subscription and retry after the delay, or raise maxFramesPerSecond where syncNode() is called',
     });
   }
 }
@@ -388,7 +326,26 @@ export class SocketUnauthenticatedError extends RealtimeError {
     super({
       code: 'X_SOCKET_UNAUTHENTICATED',
       cause: `the websocket upgrade was refused: ${args.reason}`,
-      fix: 'send the credential createSyncNode({ authenticate }) reads on the upgrade request, or return an anonymous Actor from it to admit this socket',
+      fix: 'send the credential syncNode({ authenticate }) reads on the upgrade request, or return an anonymous Actor from it to admit this socket',
+    });
+  }
+}
+
+/**
+ * One principal — an actor, or an anonymous caller's network — already holds this node's per-
+ * principal share of sockets. Answered on the upgrade with 429, before a socket exists. The
+ * principal is the node's own key (`actor:<id>` / `address:<network>`), never request text.
+ */
+export class SocketLimitError extends RealtimeError {
+  constructor(args: { principal: string; limit: number }) {
+    // An anonymous network's cap is 8 x `maxSocketsPerActor` (`principal-sockets.ts`), so the
+    // value to set is derived from the actor cap either way, never the limit this socket hit.
+    const network = args.principal.startsWith('address:');
+    const perActor = network ? Math.ceil(args.limit / 8) : args.limit;
+    super({
+      code: 'X_SOCKET_LIMIT',
+      cause: `${args.principal} already holds ${args.limit} sockets on this sync node — the per-principal cap${network ? ' (an anonymous network gets 8 x realtime.maxSocketsPerActor)' : ''}`,
+      fix: `defineConfig({ realtime: { maxSocketsPerActor: ${perActor * 2} } })   # in app.config.ts — or maxSocketsPerActor on syncNode({…}) where a host builds its own; or close other tabs of this app`,
     });
   }
 }
@@ -414,7 +371,7 @@ export class SocketOriginRefusedError extends RealtimeError {
     super({
       code: 'X_SOCKET_ORIGIN_REFUSED',
       cause: `the websocket upgrade was refused: ${args.reason} — asked from ${asked ?? 'an origin that cannot be rendered'}; this node admits ${list}`,
-      fix: `export APP_URL=${asked ?? 'https://www.example.com'}   # on the sync role, and only when that is the origin your pages are served on (or createSyncNode({ allowedOrigins }))`,
+      fix: `export APP_URL=${asked ?? 'https://www.example.com'}   # on the sync role, and only when that is the origin your pages are served on (or syncNode({ allowedOrigins }))`,
     });
   }
 }

package/src/first-paint-hold.ts

@@ -0,0 +1,49 @@
+// What a realtime island's bootstrap awaits before its `mount` may run (#506, owner option 3): the
+// page boot's disk restore AND the outbox it opened, so the island's first render already carries
+// the overlays a reload rebuilds from the queue — never the server's stale count. Capped, because
+// an IndexedDB that hangs must cost the hold, never the island.
+
+import { peekOutbox } from './outbox-slot';
+import { pageRealtime } from './page-store';
+
+/**
+ * The longest a realtime island waits on the restore before it mounts anyway. A warm IndexedDB
+ * opens in tens of milliseconds; a second is a disk that is not answering, and past it the island
+ * paints what it has. Below `@ultimat3/render`'s `ISLAND_HOLD_MS`, which reveals the server's
+ * markup regardless — so this cap, not that one, is the one a slow disk meets.
+ */
+export const FIRST_PAINT_HOLD_MS = 1_000;
+
+/** `settled` — the restore finished (or was refused; there is nothing more to wait for). */
+export type FirstPaintHold = 'settled' | 'capped';
+
+/**
+ * Resolves once the page's records are back AND its outbox is open — what `useMutation` rebuilds a
+ * queued write's overlay from, synchronously from then on — or at the cap. Never rejects: a hold
+ * that threw would take the island's module graph, and with it the island, down with the disk.
+ * A page with no boot resolves at once (`booted` does, and no outbox is seated). No options: the
+ * cap is the constant, and an option would ship its finite-number screen (~550 B) in every
+ * realtime island to serve tests that can stub the timer instead.
+ */
+export async function holdFirstPaint(): Promise<FirstPaintHold> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const capped = new Promise<FirstPaintHold>((resolve) => {
+    timer = setTimeout(() => resolve('capped'), FIRST_PAINT_HOLD_MS);
+  });
+  try {
+    return await Promise.race([restored(), capped]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function restored(): Promise<FirstPaintHold> {
+  try {
+    await pageRealtime().booted;
+    // Read after the boot, never before: the boot seats the outbox as its last step.
+    await peekOutbox()?.ready;
+  } catch {
+    // The boot already reported what the disk refused (`boot.ts`); the hold only stops waiting.
+  }
+  return 'settled';
+}

package/src/idb-types.ts

@@ -1,7 +1,7 @@
 /**
  * The slice of IndexedDB `local-store-idb.ts` touches, as structural types: the browser's
- * `indexedDB` satisfies them and so does `idb-fake.ts`, so the store is tested against the same
- * surface it runs on without a DOM shim.
+ * `indexedDB` satisfies them and so does `idb-fake-fixture.ts`, so the store is tested against the
+ * same surface it runs on without a DOM shim.
  */
 
 export interface IdbRequestLike<T> {

package/src/index.ts

@@ -3,6 +3,12 @@
 // Nothing here reaches `nats`, a Postgres socket or the sync node; those are `./server`, and
 // `packages/cli/src/realtime-browser-barrel.test.ts` is the build error that keeps them apart.
 
+// Imported bare, and the one module `sideEffects` lists: a page rebuilds a sync node's refusal by
+// code (`refusalError`) and `page-errors.ts` constructs codes from it without importing it, so
+// every chunk reaching this barrel registers the titles. `SIDE_EFFECTS_ANCHORS` carries the
+// argument and `bun run side-effects` enforces it.
+import './error-titles';
+
 // ---- the client's one stateless piece, reusable against an app's own store ----------------------
 export { applyPatches, orderAfterPatches } from './apply-patches';
 // ---- channels: the declaration is the only way to spell a topic, and the frames it rides --------
@@ -84,10 +90,15 @@ export {
   TransportUnavailableError,
   WindowReadTimeoutError,
 } from './errors';
+// ---- the page: one record store, one socket, installed by the island bootstrap ------------------
+export {
+  FIRST_PAINT_HOLD_MS,
+  type FirstPaintHold,
+  holdFirstPaint,
+} from './first-paint-hold';
 // ---- shared value domain ---------------------------------------------------------------------
 export {
   changedColumns,
-  isJsonObject,
   isRow,
   type JsonObject,
   type JsonValue,
@@ -99,7 +110,8 @@ export { type LiveState, type Registration, RowWindows, unnamedType } from './li
 // ---- offline: the durable store, the persisted records, the one outbox (plan 101 slice 12) ------
 export {
   type LocalStore,
-  MemoryLocalStore,
+  type MemoryLocalStore,
+  memoryLocalStore,
   openLocalStore,
   pageLocalStore,
   scopeKey,
@@ -107,22 +119,22 @@ export {
 // ---- the offline outbox (wired over HTTP in plan 101 slice 12) ----------------------------------
 export {
   type DrainReport,
-  MemoryQueueStore,
+  type MemoryQueueStore,
   type MutationSender,
   type MutationStatus,
+  memoryQueueStore,
   OfflineQueue,
   type QueuedMutation,
   type QueueState,
   type QueueStore,
 } from './offline-queue';
 export {
-  createOutbox,
   listenForDrain,
+  localOutbox,
   type OutboxEntry,
   type PageOutbox,
   pageOutbox,
 } from './page-outbox';
-// ---- the page: one record store, one socket, installed by the island bootstrap ------------------
 export { hasPageSocket, type SyncTarget } from './page-store';
 export { installRealtime, type RealtimeInstall } from './reactivity';
 export { persistedTypes, type RecordPersister, recordPersister } from './record-persister';
@@ -182,4 +194,10 @@ export {
   useMutationQueue,
 } from './use-mutation';
 export { type QueryAccessor, type QueryOptions, type QueryRef, useQuery } from './use-query';
-export { type RecordAccessor, type RecordsAccessor, useRecord, useRecords } from './use-record';
+export {
+  type RecordAccessor,
+  type RecordSelection,
+  type RecordsAccessor,
+  useRecord,
+  useRecords,
+} from './use-record';

package/src/json.ts

@@ -8,6 +8,8 @@
 // for having no reader. A 32-bit hash nothing calls is a hash the next caller reaches for as a
 // sharing key, which is the one thing it must never be.
 
+import { isJsonObject } from '@ultimat3/core/page';
+
 export type JsonValue =
   | string
   | number
@@ -39,14 +41,25 @@ export interface RowPatch {
    * projection on the server. Absent means the key is the `id`.
    */
   readonly key?: string;
+  /**
+   * The write that made this patch's change (`ChangeEvent.write`), held only on the RETAINED
+   * patch so a delta resume can name it. Server-side only: a frame names its writes once, in
+   * `PatchFrame.writes`, so `live-resume.ts` strips it before sending and `decode` never reads it.
+   */
+  readonly write?: string;
 }
 
-export function isJsonObject(value: unknown): value is JsonObject {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Core's `isJsonObject`, read as the wire's value domain. Sound ONLY for a value that came out of
+ * `JSON.parse` (a frame, a stored row): every member of one is a `JsonValue` by construction, which
+ * is the one thing core's shape check cannot know and so does not claim. One implementation, core's.
+ */
+export function isParsedJsonObject(value: unknown): value is JsonObject {
+  return isJsonObject(value);
 }
 
 export function isRow(value: unknown): value is Row {
-  return isJsonObject(value) && typeof value['id'] === 'string';
+  return isParsedJsonObject(value) && typeof value['id'] === 'string';
 }
 
 /** Shallow diff used to keep update patches minimal — the pipeline never ships unchanged columns. */

package/src/live-contract.ts

@@ -34,6 +34,13 @@ export interface LiveQueryDefinition<R extends Row = Row> {
   snapshot(args: { input: JsonValue; tenant: string | null }): Promise<SnapshotResult<R>>;
   /** Subscribe-time gate. Throws to deny — the same `policy` used by HTTP, jobs, and MCP. */
   authorize?(args: { actor: Actor | null; input: JsonValue }): void | Promise<void>;
+  /**
+   * The read's declared `rateLimit:`, spent once per SUBSCRIBE, after `authorize` allowed it —
+   * the same bucket HTTP, a paged read and the MCP tool spend. Per subscriber because the shared
+   * window builds with no subject and spends nothing; never on a re-authorization, because the
+   * subscription it re-decides was already paid for. Throws `X_RATE_LIMITED` to refuse.
+   */
+  spend?(caller: LiveSpender): Promise<void>;
   /** Row-level gate, evaluated per subscriber. The only row filter in the pipeline. */
   visible(args: { actor: Actor | null; row: R; input: JsonValue }): boolean | Promise<boolean>;
   /** Built once per `qid`, since a qid pins both the query and its input. */
@@ -59,6 +66,13 @@ export interface LiveQueryDefinition<R extends Row = Row> {
   prepare?(input: JsonValue): Promise<void>;
 }
 
+/** Who a live subscribe is charged to: the socket's actor, else its address, on the node's clock. */
+export interface LiveSpender {
+  readonly actor: Actor | null;
+  readonly clientAddress: string | null;
+  readonly nowMs: number;
+}
+
 export interface LiveSubscription {
   readonly sid: string;
   readonly qid: string;

package/src/live-definition.ts

@@ -9,8 +9,14 @@
 // every time. Collapsing the second onto the first is privilege escalation with a cache hit rate.
 
 import type { Ctx } from '@ultimat3/core';
-import { finiteOption, runWithContext, serviceActor, withChildContext } from '@ultimat3/core';
-import { type AnyQuery, queryHash, queryName } from '@ultimat3/query';
+import {
+  anonymousActor,
+  finiteOption,
+  runWithContext,
+  serviceActor,
+  withChildContext,
+} from '@ultimat3/core';
+import { type AnyQuery, queryHash, queryName, spendQueryLimit } from '@ultimat3/query';
 import { LiveRowUnidentifiedError } from './errors';
 import { isRow, type JsonValue, type Row } from './json';
 import type { LiveQueryDefinition, SnapshotResult } from './live-contract';
@@ -182,6 +188,10 @@ export function liveQueryDefinition(
     // memoised anywhere: `authorize` runs on every subscribe, `visible` on every row of every
     // delivery, and there is no key here an actor could share with another actor.
     authorize: authorizeWithPolicy(target.policy, { query: name, ctx: options.ctx }),
+    // The read's own `rateLimit:` bucket, per subscriber — the one HTTP and MCP spend. A socket
+    // with no actor is the anonymous reader, keyed by its address as an unauthenticated HTTP read is.
+    spend: ({ actor, clientAddress, nowMs }) =>
+      spendQueryLimit(target, { actor: actor ?? anonymousActor(), clientAddress, nowMs }),
     visible: visibleWithPolicy(target.policy, { query: name, ctx: options.ctx }),
   };
 }

package/src/live-deliver.ts

@@ -0,0 +1,55 @@
+// One change, fanned out over every live window on the node. Split from `live-query.ts` at its
+// size ceiling: the registry owns who holds which window, this owns the ordering of one delivery.
+
+import type { ChangeEvent } from './changefeed';
+import { type FanoutDeps, fanoutChange } from './live-fanout';
+import type { QueryEntry } from './query-window';
+
+/**
+ * Fan one change out. Matched once per query id, authorized once per subscriber. Returns the
+ * number of frames sent — the metric the reconnect benchmark watches.
+ *
+ * Each entry's turn is taken in that entry's lane. Nothing upstream orders this: `sync` fires
+ * `void registry.deliver(change)` straight off the bus subscription, so two changes arriving back
+ * to back would otherwise interleave inside one query id — lsn 2 delivered before lsn 1, the
+ * subscriber's cursor rewound to 1, and every gate deciding against whichever window won.
+ *
+ * Every lane is *entered* before any of them is awaited, and nothing inside a fanout takes a
+ * second lane, so holding all of them at once cannot be a cycle. That is what makes the ordering
+ * claim true: two deliveries queue onto each query id in call order, serialized per query id and
+ * never per node — awaiting one entry before entering the next made one slow policy pass the
+ * whole node's pace, and let a lane that threw skip every entry behind it with nobody desynced.
+ */
+export async function deliverChange(
+  entries: Iterable<QueryEntry>,
+  fanout: FanoutDeps,
+  change: ChangeEvent,
+  onStale: (count: number) => void,
+): Promise<number> {
+  const lanes = [...entries].map(async (entry) => {
+    try {
+      const result = await entry.lock.run(() => fanoutChange(fanout, entry, change));
+      onStale(result.stale);
+      return result.sent;
+    } catch (error) {
+      // The window advanced under a fanout that did not finish, so every subscriber of this one
+      // query id now holds a cursor below the change and no later flush would correct them:
+      // desynced here, re-snapshotted on the next one. Silent divergence is the whole reason
+      // `markDesynced` exists, and skipping this is how a failure became one.
+      for (const subscription of entry.subscribers.values()) {
+        subscription.socket.markDesynced(subscription.sid);
+      }
+      throw error;
+    }
+  });
+  // `allSettled`, so one lane's rejection neither cancels the others nor goes unhandled. The
+  // first failure still reaches the caller — `sync` logs it — but it costs one query id.
+  let sent = 0;
+  let failure: { readonly error: unknown } | null = null;
+  for (const lane of await Promise.allSettled(lanes)) {
+    if (lane.status === 'fulfilled') sent += lane.value;
+    else failure ??= { error: lane.reason };
+  }
+  if (failure !== null) throw failure.error;
+  return sent;
+}